baton

<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/TheKathan/baton/main/assets/banner-dark.svg"><img alt="baton: hand-offs for AI agents that build software together" src="https://raw.githubusercontent.com/TheKathan/baton/main/assets/banner-light.svg" width="720"></picture></p> <p align="center"> <a href="https://github.com/TheKathan/baton/actions/workflows/test.yml"><img alt="tests" src="https://github.com/TheKathan/baton/actions/workflows/test.yml/badge.svg"></a> <a href="https://pypi.org/project/baton-handoff/"><img alt="PyPI" src="https://img.shields.io/pypi/v/baton-handoff"></a> <img alt="license" src="https://img.shields.io/github/license/TheKathan/baton"> <img alt="Python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB"> <img alt="dependencies: none" src="https://img.shields.io/badge/dependencies-none-brightgreen"> </p>

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

<p align="center"><img alt="Two real coding agents from different vendors share one baton board. Codex, as frontend, asks backend which route serves the health check (Q-001). Claude Code, as backend, runs baton handoff and is refused because Q-001 is unanswered; it reads the question, answers and closes it, and the hand-off goes through as H-002 without --force. A live board along the bottom shows each entry as it is written. Captioned; the agents' output is unchanged" src="https://raw.githubusercontent.com/TheKathan/baton/main/assets/agent-demo.gif" width="800"><br>_{Two real agents, unscripted: Codex asks, Claude Code is refused until it answers, and the live board records it all.}</p>

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

<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/TheKathan/baton/main/assets/how-it-works-animated-dark.svg"><img alt="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" src="https://raw.githubusercontent.com/TheKathan/baton/main/assets/how-it-works-animated-light.svg" width="720"></picture></p>

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)