ai-baton

中文

Portable, auditable, file-first handoff protocol for AI assistants.

Lets you move between AI tools — Claude Code, Codex CLI, Cursor, or anything else that reads/writes files — on the same long-running project without re-explaining context every time. State lives in plain Markdown + YAML files in your own repo: a memory/ for durable facts and decisions, a status/CURRENT_STATUS.md for what's happening right now, an append-only evidence/ trail, handover/ snapshots, and archive/ for superseded plans. No server, no vector DB, no vendor plugin required — every change is just a git diff.

Requires local filesystem access — this works with tools that run on your machine or have been given access to a folder (Claude Code, Codex CLI, Cursor, Windsurf, Claude Desktop with a filesystem connector, etc.). Plain web ChatGPT or web Claude.ai chat, without file access, can't read PROTOCOL.md at all, regardless of Agent Skills support.

Not the first system aiming at cross-tool AI memory — Mem0, OpenMemory, and Letta solve overlapping problems with a vector store and/or an agent runtime. This makes the opposite trade-off: zero infrastructure and git-native auditability, at the cost of semantic search and automatic extraction. See docs/comparison.md.

Status

Pre-alpha. pip install ai-baton-tool (PyPI distribution name differs from the ai-baton command — an existing unrelated package blocked that name). Working: the spec (SPEC.md), the init / validate / status / list / workspace set / skill install CLI, a default workspace convention (~/ai-baton-workspace/<project-name>/, its root chosen once and remembered via ~/.ai-baton/config.json, discoverable across tools/sessions via ai-baton list), a full worked example (examples/demo-project/), and an Agent Skills skill — ai-baton skill install puts it where Claude Code, Codex CLI, and GitHub Copilot look for it, confirmed triggering live in all three (real user tests: Codex CLI discovered and ran the skill correctly, though full compliance with every rule — e.g. the canary tag, guided-question UI — wasn't confirmed there; Copilot discovered and ran it too, and that test directly found two real bugs — reading an unrelated sibling project's files into a new one, and skipping the backfill question — both fixed as a result). Not yet tested in Cursor, though Cursor's own docs say it reads skills from the same .agents/skills//.claude/skills/ locations this tool installs into. validate also flags well-known credential formats (AWS/GitHub/Slack keys, private key blocks) as a heuristic safety net, not a full secrets scanner, and warns (per-project configurable via .ai-baton.json) when memory/ gets large enough to be a real token cost every session. Bad paths now fail with a plain error message instead of a Python traceback. 49 tests pass locally. Not built: semantic search (by design) and any automated measurement of handoff effectiveness (methodology sketched in docs/metrics.md, nothing wired up).

Quick orientation

• docs/quickstart.md — install and try it.
• SPEC.md — the protocol.
• docs/comparison.md — vs. Mem0 / OpenMemory / Letta / Letta Code.
• docs/metrics.md — how we'd measure handoff quality.
• examples/demo-project/ — worked example.
• .agents/skills/ai-baton/SKILL.md — install once, an AI tool follows the protocol without being reminded.

License

MIT — see LICENSE.