Metadata-Version: 2.5
Name: ai-baton-tool
Version: 0.0.13
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, triggered live in Claude Code but not yet in Codex or 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).
