# ctxbaton

> Pass context between AI agents like a relay baton.

When you switch agents mid-project — because you ran out of tokens, changed tools, or just opened a new session — ctxbaton makes sure nothing is lost. Every agent picks up exactly where the last one stopped.

## How it works

A lightweight hook fires after every agent turn and saves a snapshot: the current git hash, todo state diff, and transcript path. No tokens spent. No agent cooperation required. It just happens.

When you resume — in the same agent or a different one — run:

```bash
ctxbaton context    # what are we building, what's open, what was decided
ctxbaton replay     # what changed since I was last here
```

## Install

```bash
uvx ctxbaton hooks install   # wire up the Claude Code Stop hook
uvx ctxbaton init            # write AGENTS.md into your project
```

Requires [uv](https://docs.astral.sh/uv/).

## Commands

```bash
ctxbaton context              # full project context — spec, todos, handoff, decisions
ctxbaton replay               # what changed since last snapshot (git diff + todo changes)
ctxbaton replay --since 2h    # what changed in the last 2 hours
ctxbaton search "auth"        # semantic search across all memories

ctxbaton todo list            # open tasks
ctxbaton todo done <id>       # mark a task done
ctxbaton todo start <id>      # mark a task in progress

ctxbaton memory save --type decision "use JWT over sessions because..."
ctxbaton memory save --type handoff  "stopped mid-auth, next: refresh tokens"
ctxbaton memory save --type spec     "build a REST API with FastAPI"
ctxbaton memory save --type todo     "add rate limiting"

ctxbaton snapshot list        # full snapshot history with git hashes
ctxbaton hooks install        # install Claude Code Stop hook
ctxbaton serve                # start as MCP server
```

## Memory types

| Type | Purpose |
|------|---------|
| `spec` | The current goal or plan |
| `todo` | A task with status (pending / in_progress / done) |
| `decision` | An architecture or design choice with rationale |
| `handoff` | State snapshot when switching agents or sessions |
| `progress` | What has been completed |
| `general` | Anything else |

## Cross-agent continuity

ctxbaton is agent-agnostic. Claude Code, OpenCode, Codex, Cursor — they all call the same CLI and write to the same store.

Each project gets its own isolated DB at:
```
~/.ctxbaton/projects/-Users-you-dev-myproject/memories.db
```

The path mirrors the project directory (same convention as Claude Code's own memory files), so there's no config needed — open a project, run `ctxbaton context`, done.

## Automatic snapshots

Install the Stop hook once:

```bash
ctxbaton hooks install
```

After that, every time an agent finishes a turn, ctxbaton saves:
- The current git hash and branch
- A diff of what todos changed
- A reference to the session transcript

No tokens. No agent cooperation. Just a shell script that runs in milliseconds.

## Agent instructions

Run once in your project directory:

```bash
ctxbaton init
```

This writes `AGENTS.md` into the project root. Claude Code, Codex, and OpenCode all read it automatically — every agent will run `ctxbaton resume` at session start and `ctxbaton handoff` before switching.

## MCP server

```bash
ctxbaton serve
```

Register in Claude Code:
```bash
claude mcp add ctxbaton --env MEMORY_PROJECT=$(pwd) -- uvx ctxbaton serve
```

Or in any MCP-compatible client:
```json
{
  "mcpServers": {
    "ctxbaton": {
      "command": "uvx",
      "args": ["ctxbaton", "serve"],
      "env": { "MEMORY_PROJECT": "/path/to/your/project" }
    }
  }
}
```

## Storage

Memories are stored in SQLite with local embeddings ([BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5), ~40MB, downloaded once). No API keys. Works offline.

## License

MIT — [melonkernel/ctxbaton](https://github.com/melonkernel/ctxbaton)
