license

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.

Try it in one command: uvx baton-handoff demo

_{Two real agents, unscripted: Codex asks, Claude Code is refused until it answers, and the live board records it all.}

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

Use	What you get
Agents side by side on your machine	One board for every agent, even across git worktrees.
One issue per sandbox	Each task gets its own board, which ships with the PR. Sandbox mode
Your team's rules	Policies refuse or flag entries that skip what your team expects. Policies
CI on GitHub	Actions that run a task's board around your agent and check it on the PR: setup-baton, baton-task, baton-check on the GitHub Marketplace. How to use them
Keeping an eye on the work	A local kanban board and metrics: who is blocked, who has the baton, what is stale. Commands

How it works

How baton works, as a conversation where every message is a typed entry in an append-only log: frontend asks backend which route serves the health check (Q-001); backend's hand-off to qa is refused and nothing is appended, because Q-001 is unanswered; backend answers, and the hand-off goes through as H-002, so qa takes over

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)