Metadata-Version: 2.5
Name: ai-baton-tool
Version: 0.0.16
Summary: Portable, auditable, file-first handoff protocol for AI assistants.
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# ai-baton

[中文](README.zh-CN.md)

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`](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](https://agentskills.io/)
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`](docs/quickstart.md) — install and try it.
- [`SPEC.md`](SPEC.md) — the protocol.
- [`docs/comparison.md`](docs/comparison.md) — vs. Mem0 / OpenMemory /
  Letta / Letta Code.
- [`docs/metrics.md`](docs/metrics.md) — how we'd measure handoff quality.
- [`examples/demo-project/`](examples/demo-project/) — worked example.
- [`.agents/skills/ai-baton/SKILL.md`](.agents/skills/ai-baton/SKILL.md) —
  install once, an AI tool follows the protocol without being reminded.

## License

MIT — see [`LICENSE`](LICENSE).
