ctxbaton 0.2.2

Pass context between AI agents like a relay baton — persistent memory, snapshots, and semantic search across sessions

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:

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

Install

uv tool install ctxbaton
ctxbaton hooks install   # wire up the Claude Code Stop hook

Or run without installing: uvx ctxbaton

Requires Python 3.11+ and uv.

Commands

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:

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:

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

ctxbaton serve

Register in Claude Code:

claude mcp add ctxbaton --env MEMORY_PROJECT=$(pwd) -- uvx ctxbaton serve

Or in any MCP-compatible client:

{
  "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, ~40MB, downloaded once). No API keys. Works offline.

License

MIT — melonkernel/ctxbaton