Baton

5 agent adapters · zero-cost session capture · zero-token codebase scan · 1142 tests passing

Stop re-explaining your project to every AI. One file, every agent, always in sync.

---

The problem

You switch from Claude Code to Cursor. Cursor has no idea what you decided yesterday. You switch back — Claude Code has no idea what Cursor just changed. Ten minutes of every session goes to rebuilding context you already captured somewhere.

The real problem isn't tool-switching, it's memory loss:

• The agent re-suggests what you already rejected. You ruled out TypeScript last week. Nothing recorded that, so it suggests it again.
• The agent "fixes" things that are intentionally weird. That auth callback looks like a bug — it's the OAuth PKCE flow. The agent "fixes" it. You revert it.
• Decisions vanish when sessions end. Three sessions later, a new agent quietly reverses a call you made for a reason nobody wrote down.

Baton fixes this with one file, BATON.md, that you own and every agent reads:

BATON.md  ←── the only file you edit (plain Markdown + YAML)
    │
    └── baton sync delivers it to every agent:
        ├── CLAUDE.md                          (Claude Code)
        ├── AGENTS.md                          (OpenAI Codex)
        ├── .cursor/rules/baton.mdc            (Cursor)
        ├── GEMINI.md                          (Gemini CLI)
        └── .github/copilot-instructions.md   (GitHub Copilot)

Generated files are not source files — gitignore them, Baton recreates them from BATON.md on demand. MIT-licensed, no SaaS, no lock-in.

---

Install

pip install baton-pass

Python 3.10+ required.

---

Quickstart

baton init   # scaffold BATON.md, .baton.toml, git hooks
# ...fill in project purpose, stack decisions, hard constraints (5-10 min)...
baton sync   # push BATON.md -> every agent's config file
baton end    # capture what changed this session -- free, no API key

Already have an undocumented codebase? Skip the blank page:

baton init --scan    # draft decisions/landmines from deps, TODOs, README, PR history -- no LLM
baton review          # accept / edit / delete each draft

---

Commands

Core loop

Command	What it does
baton init	Scaffold BATON.md, .baton.toml, git hooks
baton sync	Push BATON.md → all enabled agent config files
baton end	Capture the session into BATON.md — free by default, LLM optional
baton status	Show which agent files are in-sync, drifted, or missing
baton score	Grade BATON.md's memory quality out of 100

Bootstrapping an existing codebase

Command	What it does
baton init --scan	Zero-token scan of manifests, TODO/HACK comments, README/ADRs, PR history
baton review	Accept / edit / delete scan-drafted entries before they count anywhere

Keeping BATON.md healthy

Command	What it does
baton health	Report token budget + staleness findings (read-only)
baton trim	Prune stale entries — interactive, auto, budget-targeted, or chain-compressing
baton analyze	Validate internal consistency — broken refs, duplicate ids, stale header
baton clarify	Resolve unresolved open questions one at a time
baton supersede <old> --with <new>	Record that a new entry replaces an old one
baton history <id>	Show an entry's full supersession timeline

Guardrails

Command	What it does
baton check --drift	Detect if the codebase still matches what BATON.md claims
baton hooks install	(Re)install the advisory drift-check git hook
baton doctor	Diagnose your setup — validity, adapters, agent files, API keys

Focus & automation

Command	What it does
baton scope "<task>"	Shrink synced context to entries relevant to the task at hand
baton install-skill	Install the Claude Code skill for automatic session capture

---

How it works

Managed blocks, never full-file overwrites. baton sync only rewrites the region between <!-- BATON:START --> / <!-- BATON:END --> markers in each agent file — hand-written content around it is untouched. baton status detects drift with zero LLM calls.

Session capture, cheapest tier first. baton end defaults to a free heuristic built from your git diff and commit log. --apply reads a pre-drafted delta from stdin (what baton install-skill wires up for Claude Code). --api calls an LLM for a richer summary. Worst case is always "captured at reduced fidelity" — never "lost because no key was set."

Zero-token codebase scanning. baton init --scan drafts entries from manifest deps, HACK/FIXME/TODO comments, README/ADRs, and PR history — no LLM. Drafts carry status: pending_review and stay invisible to sync/score/drift until baton review accepts them.

Reality drift detection. baton check --drift checks whether the code still matches BATON.md's claims — a rejected dependency re-added, a decision's evidence deleted, a landmine marker touched. Fully offline. Exit codes: 0 clean, 1 warn, 2 block. Also ships as a GitHub Action.

Keeping it lean. baton health reports token budget and staleness; baton trim prunes it back down. baton scope "<task>" narrows what's synced to what's relevant right now. baton supersede / baton history record that one entry replaced another without losing the record of why the old one existed.

---

What lives in BATON.md

Section	What it prevents
laws	Agents violating hard constraints you've already set
decisions	Agents re-litigating choices that are already made
anti_decisions	Agents re-suggesting approaches you explicitly rejected
landmines	Agents "fixing" code that is intentionally weird
open_questions	Agents making unilateral calls on things you haven't decided
stack	Agents picking wrong library versions or missing gotchas
current_sprint	Agents working on the wrong thing or duplicating done work
sessions	Agents starting blind — the running log of what happened

baton score grades how well these are filled in. Any decision/anti_decision/landmine can carry supersedes: [...]; any entry can be marked global: true to survive scope filtering; scan-drafted entries carry status: pending_review.

---

LLM providers (optional)

Everything is deterministic by default. Three commands can call an LLM:

Command	Calls out	Needs a flag?
baton end --api	Every run	Yes — --api
baton analyze --deep	Every run	Yes — --deep
baton clarify	Only to classify resolved/discussed	No — auto-fires if ANTHROPIC_API_KEY is set

Provider	Install	Auth
Anthropic (default)	included	ANTHROPIC_API_KEY
OpenAI	pip install "baton-pass[openai]"	OPENAI_API_KEY
Google Vertex	pip install "baton-pass[vertex]"	GOOGLE_APPLICATION_CREDENTIALS

pip install "baton-pass[tokens]" adds tiktoken for exact baton health token counts (word-count fallback otherwise). [all] installs every extra.

---

Supported AI coding tools

Tool	Config file	Auto-detected
Claude Code	CLAUDE.md	Yes
Cursor	.cursor/rules/baton.mdc	Yes
GitHub Copilot	.github/copilot-instructions.md	Yes
OpenAI Codex	AGENTS.md	Yes
Gemini CLI	GEMINI.md	Yes

Don't see your tool? An adapter is ~50 lines — see CONTRIBUTING.md.

---

Configuration

# .baton.toml
[baton]
llm_provider = "anthropic"   # anthropic | openai | vertex (only for --api / --deep)
min_diff_lines = 10          # skip baton end if the diff is smaller than this
auto_sync = true             # re-sync agent files automatically after baton end

[adapters]
enabled = []                  # [] = auto-detect

[health]
token_warn = 4000
token_error = 8000
staleness_question_days = 30

---

Contributing

Baton is MIT-licensed and looking for contributors and users. See CONTRIBUTING.md:

• New agent adapter — ~50 lines
• New LLM provider — ~30 lines
• New drift detector or scan source — one pure function + tests
• Bug reports and feedback — open an issue

---

License

MIT — see LICENSE.

Full version history: CHANGELOG.md. Latest release write-up: release-notes-v0.2.0.md.

---

ai coding assistant · claude code · cursor ide · github copilot · gemini cli · codex · ai context management · vibe coding · structured project memory · llm-agnostic · context drift detection · github actions · open source devtools