baton

One protocol. Any agent. Continuous momentum.

baton is an open handoff protocol for AI coding agents. It preserves working context in a stable markdown format so one agent, IDE, or shell session can stop and another can resume without the human re-briefing everything.

---

Why baton exists

Context loss is one of the worst failure modes in agent-driven development. The agent forgets:

• what was already completed
• what is in flight
• which decisions were made and why
• which files matter
• what the next exact move should be

Without a protocol, the human becomes the continuity layer. Baton turns that continuity into a portable artifact.

What baton produces

Every baton handoff is a pair of files:

.baton/
  handoff-2026-05-05T14-10-03Z.md   -> concise brief for the next agent
  session-2026-05-05T14-10-03Z.md   -> deeper session log for humans and recovery

The files are plain markdown with YAML frontmatter. They are readable by humans, parseable by tools, and stable across agent ecosystems.

Core ideas

• Shared schema: the contract lives in core/SCHEMA.md
• Agent adapters: each tool gets its own installation and instruction surface under agents/
• Neutral storage: baton files live in .baton/ in the project root, or ~/.baton/ as fallback
• Immutable records: handoffs are created once and then treated as historical state
• Resume from action: every handoff ends with an exact Start Here instruction

Supported agents

Agent	Trigger	Auto-trigger	Adapter
Claude Code	/handoff	PreCompact hook	agents/claude-code/
Cursor	create handoff	Proactive rule	agents/cursor/
Codex	create handoff	Proactive AGENTS.md guidance	agents/codex/
Gemini CLI	create handoff	Proactive GEMINI.md guidance	agents/gemini/
Windsurf	create handoff	Proactive rule	agents/windsurf/

Claude Code currently has the deepest automation because it exposes command and hook surfaces. The other adapters are still fully usable, but they rely on persistent instructions rather than lifecycle hooks. The shared baton CLI gives every environment the same baseline pickup and handoff commands.

How the flow works

1. Install baton into the agent environment

From the baton repo:

git clone https://github.com/vishivish18/baton
cd baton
bash install.sh /path/to/your/project

The root installer auto-detects supported agent surfaces in the target project:

It also installs a shared baton launcher into ~/.local/bin/baton.

• .claude/ -> Claude Code
• .cursor/ -> Cursor
• AGENTS.md -> Codex
• GEMINI.md -> Gemini CLI
• .windsurfrules or .windsurf/ -> Windsurf

If nothing is detected, baton asks which adapter to install.

2. Use the universal baton commands when needed

Once installed, every environment can use the same shared command surface:

baton pickup
baton handoff

Use your agent as you usually would. Baton stays out of the way until you need continuity.

3. Create a handoff before context or session loss

In Claude Code you can still use /handoff and /pickup. In every other environment, or if you want a tool-neutral fallback, use baton handoff and baton pickup.

When the session is ending, context is tight, or unfinished work needs to be preserved, the active agent creates a baton handoff.

That handoff captures:

• TL;DR of the session
• completed work
• current state
• pending tasks with enough context to act
• key files changed
• decisions and rationale
• blockers and open questions
• exact instructions for the next agent

4. Resume from the latest baton file

In the next session, the agent:

1. loads the newest handoff from .baton/
2. reads the paired session log if present
3. verifies git and file state
4. summarizes where things stand
5. starts from Start Here

Install by agent

Claude Code

bash agents/claude-code/install.sh /path/to/project

What it installs:

• /handoff command
• /pickup command
• PreCompact hook prompt
• SessionEnd metadata hook
• persistent context-handoff rule

Claude assets are installed into ~/.claude/. Baton files themselves still go into .baton/ inside the project.

Cursor

bash agents/cursor/install.sh /path/to/project

Installs .cursor/rules/baton.mdc.

Codex

bash agents/codex/install.sh /path/to/project

Appends baton guidance to AGENTS.md without overwriting existing project instructions.

Gemini CLI

bash agents/gemini/install.sh /path/to/project

Appends baton guidance to GEMINI.md without overwriting existing project instructions.

Windsurf

bash agents/windsurf/install.sh /path/to/project

Installs .windsurf/rules/baton.md.

Example handoff frontmatter

---
schema_version: "1.0"
type: handoff
timestamp: "2026-05-05T14:10:03Z"
agent: "claude-sonnet-4-6"
agent_tool: "claude-code"
project: "baton"
project_dir: "/Users/you/work/baton"
branch: "main"
last_commit: "8e16e47"
trigger: "manual"
next_priority: "finish adapter-specific installers and tests"
---

The canonical definition of all required fields and body sections lives in core/SCHEMA.md.

Testing

Baton includes both automated checks and a manual workflow plan.

Automated

python3 scripts/validate-handoff.py tests/fixtures/handoff-2026-05-05T14-10-03Z.md
bash scripts/test-installers.sh
./scripts/baton pickup --path tests/fixtures/handoff-2026-05-05T14-10-03Z.md

Manual

See TESTING.md for end-to-end workflow tests across all adapters, plus edge cases like branch mismatch, repeated installs, and metadata-only stop-hook handoffs.

Repo layout

baton/
  core/
    SCHEMA.md
    handoff-template.md
    session-template.md
    create-handoff.py
  agents/
    claude-code/
      commands/
      hooks/
      rules/
      install.sh
    cursor/
      rules/
      install.sh
    codex/
      AGENTS.md
      install.sh
    gemini/
      GEMINI.md
      install.sh
    windsurf/
      rules/
      install.sh
  scripts/
    baton
    handoff.py
    pickup.py
    install-cli.sh
    validate-handoff.py
    test-installers.sh
  tests/
    fixtures/
  blog/
  TESTING.md
  install.sh
  README.md
  baton.png

Contributing an adapter

Adapters should translate the shared baton workflow into the host tool's native surface:

• slash commands when the tool supports them
• persistent rules or instruction files when it does not
• hooks only when the host exposes a reliable lifecycle hook mechanism

What should not change per adapter:

• the handoff file format
• the storage convention
• the meaning of required frontmatter fields
• the requirement that the next agent can act without asking the human to restate context

If you add a new adapter, start with:

• core/SCHEMA.md
• core/handoff-template.md
• core/session-template.md
• TESTING.md
• one of the existing adapter directories under agents/

Current status

Baton is production-usable as a protocol today.

• Claude Code: strongest automation, including hooks
• Cursor, Codex, Gemini CLI, Windsurf: installable and usable through persistent instructions
• Testing: schema validator and installer smoke tests are included in-repo

The remaining work is mostly adapter hardening: real-world end-to-end testing in each host tool, plus incremental polish around pickup UX.