baton-handoff 1.5.2

Your AI agents can't say "done" while another agent's question is still open.

baton is a shared board in your repo where coding agents ask questions, agree on contracts and hand work over. It checks every entry when it is written and keeps the record in git, so you review it in the pull request. One CLI, plain files, no server, any agent that runs a shell.

_{A real agent (Claude Code), unscripted, trimmed and captioned: refused while a question is open, it answers and hands off.}

Try it in 60 seconds

With baton installed, paste this into a terminal. It replays the recording in a scratch folder:

mkdir baton-try && cd baton-try && git init -q
baton init --roles frontend,backend,qa
baton post Q --as frontend --to backend --title "Which route serves health?" "For the status page."
baton handoff --as backend --phase S1-A --state DONE --to qa --title "S1-A backend" "Health endpoint done."
baton reply Q-001 --as backend --close "Use GET /api/health."
baton handoff --as backend --phase S1-A --state DONE --to qa --title "S1-A backend" "Health endpoint done."

The first hand-off is refused (answer first: baton show Q-001, then baton reply …) and nothing is written; after the reply it goes through as H-002. Or just run baton demo for a narrated replay on a temporary board; without installing anything, uvx baton-handoff demo.

Why baton

• No half-done hand-offs. An agent can't report done while a question to it is still open.
• Decisions don't get lost. Questions, contracts, decisions and blockers are typed entries in git, readable by humans and reviewable in a PR.
• Cheap to read. Each agent sees only what is new for it: a few thousand tokens, not the whole board.
• Any agent. Claude Code, Codex, Cursor or anything that runs a shell command.
• Nothing to run. No server, no database, no dependencies.

On a real project, moving from a hand-written board to baton cut a sprint's board from up to ~139k tokens to ~10k and ended id collisions. See the evidence.

What it's for

How it works

Agents run baton. Each write appends one event to a log in .baton/ under a lock, and readable views are generated from it. More on how it works.

Install

baton is on PyPI as baton-handoff and installs the baton command. It needs Python 3.11 or newer on macOS or Linux; macOS ships Python 3.9, so uv is the easiest route: it fetches a recent Python for you.

uv tool install baton-handoff

pipx install baton-handoff works too, and the getting started guide shows it, then how to set up your agents.

Documentation

• Getting started: install, try it, set up your agents, troubleshooting
• Why baton: evidence, how it compares, FAQ
• How it works: files, worktrees, stability, limits
• Sandbox mode: one board per task
• Commands: every command and flag, and the MCP tools
• Policies · Configuration · Board format

Contribute

Bugs, questions and ideas go to issues, and pull requests are welcome: see CONTRIBUTING and the code of conduct. If baton helps your agents, a star helps others find it.

CHANGELOG · SECURITY · LICENSE (MIT)