# ctx

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

![The ctx board: one row per worktree, showing agent status, last activity, and a distilled one-line task](docs/board.svg)

## 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.

## Requirements

- [Bun](https://bun.sh) 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

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

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

## Install

```bash
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

```bash
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](LICENSE).