ctx

A daemon-less CLI, TUI, and MCP companion for context-switching across git worktrees and Claude Code agent sessions.

The problem

Working across multiple git worktrees, each with one or more Claude Code agent sessions, makes context switching expensive.

• Returning to one tab: you forget what an agent was doing after deep work elsewhere, and waste tokens asking it to re-summarize.

• Cross-worktree overview: there is no board showing branch, agent status, last activity, and a one-line task summary across all your worktrees.

• Agent cold-start: new or resumed agent sessions re-ask or re-explore state that already exists in transcripts and git.

ctx solves all three by reading your existing Claude Code transcripts (~/.claude/projects/**/*.jsonl) and git state, distilling them into a compact per-worktree record, and serving that record to humans (CLI, TUI) and agents (hook injection, MCP) alike.

There is no background daemon. State is derived on demand and cached in one JSON file per worktree.

Related MCP server: ws-mcp

Requirements

• Bun 1.2 or newer.

• git 2.31 or newer. ctx neutralizes repository-controlled git config via GIT_CONFIG_COUNT, which older git ignores silently; rather than probe unprotected, it declines to read git state at all.

• Optional: the claude CLI on your PATH, or an ANTHROPIC_API_KEY. Without either, ctx still works in raw mode.

Try it without installing

bun install
bun src/index.ts status --no-distill

That prints the board from your existing transcripts and touches nothing outside the repo.

Install

bun install
bun src/index.ts install

install builds a compiled binary to ~/.local/bin/ctx, merges Claude Code hook entries into ~/.claude/settings.json (with a one-time backup), and registers ctx as an MCP server via claude mcp add if the claude CLI is on your PATH. Make sure ~/.local/bin is on your shell PATH.

Hooks are installed at user scope, so they run for every Claude Code session on the machine, not just in this project.

Commands

ctx [project]                 interactive TUI (the default command), optionally scoped
ctx status [project] [--no-distill] [--all]
                              board of worktrees, optionally scoped to one project
ctx recap [worktree|project|.] [--no-distill]
                              full recap for one worktree (project name works when unambiguous)
ctx inject [--cwd <dir>]      SessionStart hook target (prints compact recap)
ctx checkpoint --event <e>    hook target (stop|precompact|end|note)
ctx ui [project]              interactive TUI, optionally scoped to one project
ctx mcp                       stdio MCP server
ctx install                   install hooks + MCP config
ctx --version                 print the installed version

ctx status is the board view: one row per worktree with repo/branch, session status, last-active time, a distilled one-line task, and git facts (dirty, ahead, behind). Pass a project name to scope the board, e.g. ctx status myrepo shows only that repo's worktrees. At most 5 worktrees are distilled per run; the rest are picked up on the next refresh. ctx recap prints the fuller recap (done, decisions, next, blockers) for a single worktree. ctx inject is wired to the SessionStart hook so a resumed or new agent session gets prior context injected without asking for it. ctx checkpoint is wired to Stop, PreCompact, and SessionEnd hooks to record session lifecycle events. ctx ui is an Ink-based TUI that polls the same state for a live board. ctx mcp exposes the same data as MCP tools (get_my_context, get_sibling_status, ...) so an agent can query context directly instead of re-exploring.

Reading the board

• ● green means a Claude session wrote to its transcript in the last 5 minutes; ○ means idle or ended.

• ◐ yellow means that worktree is being distilled right now; ✗ red means the distill produced nothing (check ~/.ctx/log, usually a claude auth issue).

• The time column is last session activity, not when the row was distilled.

• (raw) in the task column means the worktree has never been distilled.

• The repo's main checkout counts as a worktree too; git itself calls it the main worktree, and agent sessions run there like anywhere else.

• In the TUI, r re-distills every visible worktree serially and each row updates as its summary lands.

Distiller auth chain

Turning a heuristic extract (a few KB, never the raw transcript) into a one-line task and structured recap requires an LLM call. ctx never requires an API key and tries, in order:

1. claude -p --model haiku subprocess - used first if the claude CLI is on PATH. This reuses your existing Claude Code login, so no extra credentials are needed.

2. ANTHROPIC_API_KEY + @anthropic-ai/sdk - used as a fallback if the CLI is unavailable or fails, calling claude-haiku-4-5 directly.

3. Raw mode - if neither is available, ctx falls back to the heuristic extract alone (no LLM summary). The board marks these worktrees as (raw) and the tools remain fully usable, just less distilled.

Distillation only runs when the transcript has changed since it was last distilled (tracked via a content hash), so repeated ctx status calls are cheap.

Design notes

The interesting problems in this codebase are mostly about untrusted input and concurrency.

Transcript content is untrusted, and it travels. A transcript records whatever an agent read: a repo's README, a fetched page, a tool result. That text is summarized by a model, stored, and then injected into other agents' sessions, including summaries of sibling worktrees. So a poisoned transcript in one worktree has a path into every sibling agent's context. Fields are collapsed to a single line before rendering, because an embedded newline can forge a line and impersonate the tool's own output; the injected block is wrapped in a delimiter with a random per-invocation suffix, because a fixed delimiter can simply be closed by the content inside it; and the model's output is length- and item-capped in code rather than trusted to obey the prompt.

Git executes what a repository's config tells it to. core.fsmonitor, filter.*.clean, and friends are commands run straight out of .git/config, and the worktree paths here come from transcripts rather than from user input. ctx enumerates a repository's resolved config and neutralizes every command-executing key via GIT_CONFIG_KEY_n environment entries rather than -c key=, because -c splits its argument at the first = and a config subsection name may legally contain one. Only repo-controlled scopes are neutralized, so a user's global git-lfs setup keeps working. --ignore-submodules=dirty stops git descending into submodules, whose own config the superproject's enumeration cannot see.

State is written by several processes at once. Hooks fire on Stop, PreCompact, and SessionEnd while the TUI polls and a distill may be mid-flight for up to a minute. Writes go through a compare-and-swap under a cross-process mkdir lock whose staleness is decided by probing the recorded pid, with an absolute age backstop so a recycled pid cannot wedge a worktree permanently.

Transcripts get large. Reading a multi-hundred-megabyte transcript whole costs gigabytes of RSS, and this runs on the TUI's event loop every 30 seconds, so both the scanner and the extractor read bounded regions and grow the window only until it contains a complete entry.

Testing

bun test        # 126 tests
bun run typecheck

The suite is mutation-verified: seeded defects (removing the state lock, dropping event validation, un-sorting the transcript scan, reverting the sanitizer) are each confirmed to fail it. That check exists because an earlier version of the suite stayed green with the entire locking apparatus deleted.

Environment variables

• CTX_DIR - overrides the state directory (default ~/.ctx). State lives at $CTX_DIR/worktrees/*.json, and errors are logged to $CTX_DIR/log.

• CLAUDE_PROJECTS_DIR - overrides the transcript root (default ~/.claude/projects).

Both are primarily useful for tests and for pointing ctx at a non-default Claude Code install.

Hooks always exit 0

ctx checkpoint and ctx inject are invoked as Claude Code hooks and always exit 0, even on internal failure. A hook that breaks the agent session is worse than one that silently no-ops, so every error path is caught, logged to $CTX_DIR/log, and swallowed. No LLM calls happen inside hook execution, so hooks stay fast.

State

Truth lives in your Claude Code transcripts and git; ~/.ctx/worktrees/*.json is a disposable cache, one file per worktree, written via temp-file-plus-atomic-rename. Delete the whole ~/.ctx directory at any time and it will be rebuilt on the next ctx status.

License

MIT - see LICENSE.