Baton is a zero-dependency MCP server that lets AI coding agents hand off work across sessions through a shared, on-disk .baton/ handoff state in each project.
Check for a baton (baton_status) — at session start, see whether handoff state exists for the project and get a one-glance summary.
Pick up the baton (baton_pick_up) — retrieve the full current handoff state plus recent history so a new agent/session continues exactly where the previous one stopped.
Pass the baton (baton_pass) — record where you stopped (handoff note required, plus optional goal, task, status, done, next, files, open questions, gotchas); merges with existing state and rewrites HANDOFF.md.
Drop breadcrumbs (baton_log) — append a lightweight mid-task progress note to the ledger without a full handoff.
Read history (baton_history) — inspect the recent handoff/progress ledger, with an optional limit.
Initialize a project (baton_init) — create .baton/ and symlink CLAUDE.md ⇄ AGENTS.md so Claude Code and Codex load identical instructions.
All tools accept an optional project path (default: cwd), and state lives as plain-text files (HANDOFF.md, .baton/baton.json, .baton/ledger.jsonl) that you can read or edit by hand.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Baton pick up where the last agent left off and summarize the handoff"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Baton is a tiny, zero-dependency MCP server that gives your agents a shared, on-disk handoff baton. One .baton/ folder per project becomes the shared brain that survives the death of any single session.
Works with Claude Code, Codex, and any MCP-capable client.
Two agents on the same repo still can't hand off work:
Instructions are siloed. Claude Code auto-reads CLAUDE.md; Codex auto-reads AGENTS.md. Point both at one folder and one of them starts blind.
Session state is private and lossy. Claude stores transcripts in ~/.claude/…, Codex in ~/.codex/…. Neither reads the other's, and replaying a raw transcript is expensive and lossy. The intent — which step you're on, what you just learned, why you stopped — lives in the context window and dies when the session ends.
So "let Codex continue what Claude started" fails: the second agent sees the files, but not the plan.
Related MCP server: ContextPocket MCP Server
Baton writes the intent to disk in a format both sides read:
File | What it holds |
| Human- and agent-readable "where we stopped / what's next." |
| Structured live state — done, next, open questions, gotchas, key files. |
| Append-only history. Crash-resilient: breadcrumbs survive even if an agent dies mid-task. |
baton_init also bridges CLAUDE.md ⇄ AGENTS.md with a symlink, so both agents load the same instructions instead of one starting blind.
No install step — it runs straight from GitHub via npx:
npx -y github:timurabi3/baton-mcp# BATON_AGENT tags this agent in every handoff
claude mcp add baton -e BATON_AGENT=claude-code -- npx -y github:timurabi3/baton-mcp[mcp_servers.baton]
command = "npx"
args = ["-y", "github:timurabi3/baton-mcp"]
env = { BATON_AGENT = "codex" }Then add one line to your instructions (CLAUDE.md / AGENTS.md):
At session start, call
baton_pick_up. Before you stop, callbaton_pass.
Claude Code ──(hits context limit)──▶ baton_pass { handoffNote, next, watchOut }
│ writes .baton/ + HANDOFF.md
Codex ──(fresh session)────────▶ baton_pick_up ◀── reads it, continuesBATON_AGENT tags each pass, so the ledger reads like a relay log:
14:02 [claude-code] pass: moved 25 project folders; venvs for ayra-caller/cashclaw need rebuild
14:05 [codex] pick_up
14:31 [codex] pass: rebuilt venvs, wired both agentsTool | When to call it |
| Session start — is there a baton here? |
| Continue where the last agent left off. Returns the full handoff + recent ledger. |
| Stopping — record where you left off (merges state, rewrites |
| Drop a mid-task progress breadcrumb. |
| Read the recent ledger. |
| Create |
Zero dependencies. MCP stdio is newline-delimited JSON-RPC 2.0 — implemented directly, so npx works offline and the whole server is auditable in a single file.
stdout is protocol-only; all logs go to stderr.
Storage is per-project (.baton/ under the project root; override with BATON_PROJECT).
The full on-disk contract lives in PROTOCOL.md — an open, agent-neutral convention, not something private to one vendor.
The baton is shared, plain-text state — read and edit .baton/ by hand any time; there's no database and no lock-in.
An unrelated package named baton-mcp exists on npm. Install from GitHub as shown above.
MIT © Timur Oral
Read the recent handoff/progress ledger for this project.
Inputs: limit, project.
Set up Baton for a project: create .baton/ and bridge CLAUDE.md <-> AGENTS.md (symlink) so both Claude Code and Codex read the same instructions.
Inputs: project.
Drop a lightweight progress breadcrumb into the ledger without a full baton pass. Use for mid-task milestones.
Inputs: note (required), project.
PASS THE BATON. Record where you're stopping so the next agent/session continues seamlessly. Merges with existing state — pass only the fields you want to update. Rewrites HANDOFF.md.
Inputs: handoffNote (required), done, goal, next, +6 more.
PICK UP THE BATON. Returns the full current handoff state + recent history so you continue exactly where the previous agent (or session) stopped. Call this before doing any work if a baton might exist.
Inputs: project.
Check if a baton (handoff state) exists for this project and get a one-glance summary. Call this at session start.
Inputs: project.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Most tools map to a distinct step in the handoff workflow with clear usage cues. status, history, and pick_up all expose handoff information at different levels of detail, so there is minor potential for confusion among the read-focused tools.
All tools share the baton_ prefix and use snake_case, which makes the set feel coherent. The mix of verb-like names (pick_up, pass, log, init) and noun-like names (status, history) is a small inconsistency, but the pattern remains predictable.
Six tools is well-scoped for a handoff utility: setup, status check, pick-up, history, progress logging, and passing cover the workflow without unnecessary bloat.
The core lifecycle is covered: initialize, check, pick up, log progress, and pass the baton. The main gap is the lack of a reset, clear, or discard operation for ending or resetting a handoff state.
Project management shared by people and AI agents, with persistent project state through MCP.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Shared project memory that keeps teammates and AI agents aligned across sessions.
Project memory, documentation and controlled secret access for AI coding agents.
