# ctxbaton setup

## Install

No install step required. Use [uvx](https://docs.astral.sh/uv/) to run directly:

```bash
uvx ctxbaton --help
```

---

## Claude Code

### 1. Install the Stop hook

```bash
uvx ctxbaton hooks install
```

This wires up automatic state capture after every agent turn. Run once — works
across all projects.

### 2. Add agent instructions to your project

```bash
uvx ctxbaton init
```

This writes `AGENTS.md` into the project root. Claude reads it automatically
and will run `ctxbaton resume` before starting work.

### 3. MCP server (optional)

If you want Claude to call ctxbaton as MCP tools rather than via Bash:

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

Or add to `.claude/settings.json` in your project:

```json
{
  "mcpServers": {
    "ctxbaton": {
      "command": "uvx",
      "args": ["ctxbaton", "serve"],
      "env": { "MEMORY_PROJECT": "/absolute/path/to/your/project" }
    }
  }
}
```

---

## Codex

Codex has no lifecycle hook, so capture is manual.

### 1. Add agent instructions to your project

```bash
uvx ctxbaton init
```

---

## OpenCode

OpenCode supports MCP natively.

### 1. Add ctxbaton to OpenCode's MCP config

In `~/.config/opencode/config.json`:

```json
{
  "mcp": {
    "servers": {
      "ctxbaton": {
        "command": "uvx",
        "args": ["ctxbaton", "serve"],
        "env": {
          "MEMORY_PROJECT": "/absolute/path/to/your/project"
        }
      }
    }
  }
}
```

### 2. Add agent instructions

```bash
uvx ctxbaton init
```

---

## Cross-agent workflow

```
Claude session ends
  → Stop hook fires automatically
  → Snapshot saved, transcript indexed

Switch to Codex or OpenCode
  → Agent reads AGENTS.md
  → Agent runs: ctxbaton resume
  → Full context loaded: spec, todos, handoff, decisions, git diff

Work continues
  → Agent runs: ctxbaton handoff "what was done, what's next"
  → Switch back to Claude
  → Claude reads CLAUDE.md, runs ctxbaton resume
```

---

## MCP tools reference

| Tool | Description |
|------|-------------|
| `resume` | Full resumption context: spec, todos, handoff, decisions, replay delta |
| `get_context` | Spec, todos, handoff, decisions (no replay) |
| `save_memory` | Save a memory (spec / todo / decision / handoff / progress / general) |
| `list_memories` | List by type / status |
| `search_memories` | Full-text search across memories |
| `get_memory` | Fetch one memory by ID |
| `update_memory` | Edit content, type, status, or tags |
| `update_todo_status` | Mark a todo pending / in_progress / done |
| `delete_memory` | Delete by ID |
| `capture_session` | Capture state from any agent |
| `save_handoff` | Save handoff note and capture state |
| `search_messages` | Full-text search over indexed transcript messages |
