baton MCP server
Commit Nov 9, 2026Enables AI coding agents to coordinate work, ask questions, and manage hand-offs using a git-based shared board.
Also known as TheKathan/baton
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is baton MCP?
baton enables AI coding agents to coordinate work, ask questions, and manage hand-offs using a git-based shared board.
Summary generated from the project's README
About baton MCP server
Coordinating multiple AI coding agents during complex software development tasks is what baton enables through a git-based shared board. It provides a structured way for agents to ask questions, agree on technical contracts, and manage hand-offs without losing critical context. Because it uses plain files stored in your repository, every decision and blocker becomes a permanent part of your git history that humans can review during pull requests.
This tool works locally via a CLI and requires no dedicated server or database, making it compatible with any agent capable of running shell commands, such as Claude Code, Codex, or Cursor. It manages state by checking entries whenever they are written, ensuring an agent cannot report a task as finished if there are still unanswered questions directed at them. Users can install it via PyPI or use uv to manage the Python 3.11+ environment required for operation.
What you can do with it
- 1Preventing incomplete task hand-offsEnsure an agent cannot signal completion if it has outstanding questions from another agent.
- 2Managing multi-agent collaborationAllow different AI agents from different vendors to work together on the same codebase.
- 3Reducing token consumptionMinimize the amount of context an agent must read by only showing relevant new entries.
- 4Automating agent oversight in CIUse GitHub Actions to verify that an agent followed the required board protocols before merging.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablethekathan/baton is public and reachablegithub.com/thekathan/baton ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/thekathan/baton ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYour 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
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
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.
baton MCP questions
How does baton prevent incomplete work hand-offs?
It refuses a hand-off if there is an unanswered question directed at the agent.
Which AI agents can use baton?
Any agent that can run shell commands, such as Claude Code, Codex, or Cursor, can use it.
How can I try baton quickly?
You can run a narrated replay on a temporary board using the command uvx baton-handoff demo.