Baton — Switch AI Without Losing Project Memory

Baton keeps tasks, progress, design rules, pitfalls, decisions, and handoffs inside your project, then carries them to another computer or AI through Git.

Supported hosts: Codex, Cursor, and Claude Code.

Where to type commands

Input	Where
`git clone ...`, installer commands	PowerShell / terminal
`Baton init`, `clock in`, `clock out`	AI chat

The terminal installs Baton. AI chat uses it. Baton init is not a Git command.

Quick start

You need Git, Node.js 18+, and PowerShell. Windows PowerShell 5.1 works on Windows. Install PowerShell 7 and use pwsh on macOS/Linux.

1. Install on this computer

git clone https://github.com/kakadeka/Baton.git "$HOME/Baton"
& "$HOME/Baton/scripts/baton-install.ps1" -Scope User

If the directory already exists:

git -C "$HOME/Baton" pull --ff-only
& "$HOME/Baton/scripts/baton-install.ps1" -Scope User

One run installs the user-level Skills for Codex, Cursor, and Claude Code. Open a new AI session afterward.

2. Initialize a project

Open the real project in your AI and send this in chat:

Baton init

Initialization fills in:

the docs/ai_memory/ project-memory skeleton;
.baton/config.json and .baton/manifest.json;
project Skills and entry files for Codex, Cursor, and Claude Code; and
.cursor/rules/baton.mdc.

Existing project documents are not overwritten. If .cursor/rules/baton.mdc is missing, rerunning initialization restores it.

The equivalent terminal command is:

& "$HOME/Baton/scripts/baton-install.ps1" -Scope Project -ProjectRoot "C:\path\to\your-project"

A readable Git HEAD and an origin remote are required for the full initialization post-check.

3. Clock in

Send this in AI chat:

clock in

The flow is: fetch → inspect branch, HEAD, dirty state, and ownership → ff-only when safe → read current state, latest handoff, unfinished tasks, and index → show the task table.

Synchronization failures, divergence, unexplained changes, or active ownership stop the workflow in read-only mode. Baton does not reset, rebase, or overwrite the worktree.

Automatic memory and semantic splitting

Automatic memory

Verified pitfalls are written immediately to knowledge/pit_experience.md and the existing index.
Long-term decisions explicitly confirmed by the user are written immediately to knowledge/tech_decision.md and the index.
When the facts or long-term value are uncertain, the AI asks whether to record the item.
Memory does not depend on a manual command, and Baton does not create a second temporary memory system.

Automatic semantic splitting

Every write checks docs/ai_memory/**/*.md automatically. No user confirmation is required. 128KB is a soft target; Baton prefers a complete section or record boundary between 116KB and 140KB.

Here, “automatic” means Codex, Cursor, or Claude Code performs the check whenever it writes project documentation through the Baton Skill. Baton does not install a background file watcher.

It does not split fenced code, tables, complete list items, handoffs, ADRs, or task records. If there is no safe boundary in the preferred range, it may extend beyond 140KB to the next complete boundary and records the reason in the index. JSON and JSONL state files are never split as text.

Everyday commands

You say	Baton does
`clock in`	Syncs Git, checks ownership, reads tasks, and lists work
`continue work`	Reads the current snapshot and continues from the next step
`complete task`	Records evidence and moves the task to acceptance
`update project docs`	Saves progress, automatic memory/splitting, and indexes
`save design spec`	Updates the matching `ui_spec/` document
`remember this pitfall/decision`	Explicit supplement; automatic memory still runs
`clock out`	Updates docs, commits, pushes, and verifies remote SHA
`check update`	Checks without changing anything
`update Baton`	Explicitly runs the updater; no background update
`repair Baton`	Updates/reinstalls, then runs init and Doctor checks

Chinese commands such as 上班啦, 继续工作, and 下班啦 are equivalent.

Clock-out flow

Persist any verified pitfall or confirmed decision missed during the work.
Update the daily log, tasks, current state, semantic splits, and indexes; write the handoff last.
Check config, Contract, allowed paths, protected paths, credentials, and ownership.
Make one closeout commit after all gates pass.
Push, then use git ls-remote to verify that remote SHA equals local HEAD.

Clock-out is complete only when remote SHA equals local HEAD and the worktree is clean. Network or permission failures leave the code safe locally and are reported as real blockers.

Moving to another computer

Clock out on computer A and confirm commit, push, and remote-SHA verification.
Clone or pull the business project on computer B.
Open it with Codex, Cursor, or Claude Code and say clock in.
If user-level Skills, project Skills, or .cursor/rules/baton.mdc are missing, run from the Baton framework checkout:

node "$HOME/Baton/scripts/baton-update.mjs" --restore-user --project "C:\path\to\your-project"

Run Baton init if .baton/config.json is missing. Project memory, project Skills, config, and manifest travel through Git; user-level installation is prepared on each computer.

Updates and repair

Baton does not promise background updates. It updates only after an explicit update Baton or repair Baton request.

Manual update:

git -C "$HOME/Baton" pull --ff-only
node "$HOME/Baton/scripts/baton-update.mjs" --restore-user --project "C:\path\to\your-project"

Repair order: read the actual error and Doctor report → update official Baton → restore user Skills → reinstall the project surface → run init/Doctor post-checks. It does not patch business code as a side effect.

Project files

your-project/
├── AGENTS.md
├── CLAUDE.md
├── .cursorrules
├── .agents/skills/baton/
├── .claude/skills/baton/
├── .cursor/skills/baton/
├── .cursor/rules/baton.mdc
├── docs/ai_memory/
└── .baton/
    ├── config.json
    ├── manifest.json
    └── local/

Track config.json and manifest.json in Git. Keep local/ and other machine-local runtime configuration out of Git.

Safety floor

No force push, reset --hard, dangerous clean, or surprise rebase.
Synchronization defaults to ff-only; divergence stops the workflow.
API keys, tokens, passwords, and private keys stay out of Git, memory, logs, and handoffs.
History is append-only or explicitly marked as superseded.
The public npm package contains only the Skills, templates, and scripts users need. It excludes project memory, tests, maintenance documents, and local private data.

Repository and license

GitHub: https://github.com/kakadeka/Baton
npm: @kakadeka/baton
License: Apache-2.0

Pass your project, not your context.