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 and Codex CLI look for it, confirmed triggering live in both (a real user test in 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). Not yet tested in Cursor. 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. 40 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.