Baton — Hand Your Project to the Next AI Without Starting Over

简体中文 | English

Baton is a project memory and handoff tool for Codex, Cursor, and Claude Code. It keeps tasks, progress, important decisions, known pitfalls, and Git state inside your project. When you switch AI tools, start a new chat, or move to another computer, the next AI can continue from the recorded state.

Baton is useful when you do not write code yourself but use AI for a long-running project. You repeat less context, lose fewer unfinished tasks, and can check whether work was really committed and pushed.

Baton is not an AI, a cloud drive, or a cloud service. It is not a background program. It is a set of project rules, templates, and scripts that AI tools read and follow only when you give a Baton command.

When Baton helps

• Switch AI tools: use Cursor yesterday, then let Codex or Claude Code continue today without explaining everything again.
• Switch computers: finish at the office, pull the project at home, and bring the progress and warnings with it.
• Start a new chat: when a conversation becomes too long or loses context, the new chat can read the current task and last handoff.
• Maintain a long project: keep decisions, rules, and pending work outside temporary chat history.
• Avoid missed Git steps: after clock out, Baton requires commit and push checks, followed by remote revision verification.
• Avoid repeated mistakes: save verified pitfalls and long-term decisions so the next AI reads them before changing the project.

Baton cannot guarantee that an AI never makes mistakes. It also does not replace GitHub. It gives project facts a stable home and asks the AI to verify claims with real files and Git results.

Understand the two installation levels

| Level | How often | Where it goes | What it does | |---|---:|---|---| | User level | Once on each computer | Skill folders for your Codex, Cursor, and Claude Code user | Teaches all three AI tools commands such as Baton init and clock in | | Project level | Once for each project | Inside the project folder | Creates project memory, handoffs, and entry files that can travel through Git |

Recommended: install the user level first, then run Baton init once in every long-running project.

One user-level installer prepares Codex, Cursor, and Claude Code together. There are not three different installation commands. User-level installation alone does not create memory files in every old project.

The first installation may use a Baton clone to run the installer. After that, standard update Baton requests use the installed baton-public-update.mjs bootstrap: it selects the newest stable tag from https://github.com/kakadeka/Baton.git, validates it in a temporary directory, and refreshes the user and current project without a local Baton source checkout or npm. The private $HOME\.baton\source.json locator is used only when you explicitly request update local Baton development build; it is never an automatic fallback for a standard update.

Beginner Windows installation

Enter the commands below in PowerShell, not in AI chat. Press the Windows key, search for “PowerShell,” and open it. Paste one block at a time, press Enter, and wait for it to finish.

Step 1: Prepare Git, Node.js, and PowerShell

Run these commands in PowerShell:

git --version
node --version
$PSVersionTable.PSVersion

You should see a Git version, a Node.js version, and a PowerShell version. Baton needs Node.js 18 or newer. Windows PowerShell 5.1 is supported.

If PowerShell says a command is not recognized, install the missing program and reopen PowerShell:

• Git: https://git-scm.com/download/win
• Node.js: https://nodejs.org/ (choose the LTS release)
• PowerShell: https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows

Step 2: Put Baton on this computer

First, check whether the default folder already exists:

Test-Path "$HOME\Baton"

• If the result is False, this is a first installation. Run:

  git clone https://github.com/kakadeka/Baton.git "$HOME\Baton"
  

• If the result is True, do not clone again. Update the existing Baton folder:

  git -C "$HOME\Baton" pull --ff-only
  

If the existing folder did not come from this repository, or the update fails, do not delete it. Give the complete error to your AI and say: repair Baton.

Step 3: Install once for all three AI tools

Run this one shared installer command in PowerShell:

& "$HOME\Baton\scripts\baton-install.ps1"

This step succeeds when the output says the user-level installation is complete and lists locations for Codex, Cursor, and Claude Code.

After installation, fully close and reopen the AI tool you want to use, or at least start a new session. An old session may not know about the newly installed Skill.

Step 4: Open your project with an AI tool

The installed Baton content is the same in all three tools. The place where you open a project and type a command is slightly different:

| AI tool | How to open the project | Where to type Baton commands | Sign of success | |---|---|---|---| | Codex | Open or select the project folder in Codex | Codex chat | The AI recognizes Baton init, checks the project, and starts project-level installation | | Cursor | Choose File → Open Folder and select the project root | Cursor AI Chat | The AI recognizes Baton init, and Baton entry and memory files appear in the project | | Claude Code | Enter the project folder in a terminal, then start Claude Code | Claude Code conversation input | The AI recognizes Baton init and reports the project initialization result |

The “project root” is the outer folder that contains the source code and usually a .git folder. Do not open only a small folder inside it.

Codex

1. Open Codex.
2. Select the project folder that you want to maintain.
3. Send Baton init in chat.
4. Wait for the AI to finish its checks. Do not enter Baton init in PowerShell.

Cursor

1. Open Cursor.
2. Choose File → Open Folder and select the project root.
3. Open Cursor AI Chat.
4. Send Baton init.

Claude Code

1. Open PowerShell and enter your project folder. For example, if the project is at C:\Projects\MyApp:

   Set-Location "C:\Projects\MyApp"
   

2. Start Claude Code in the way you normally use it.

3. Send Baton init in the Claude Code conversation input.

Step 5: Initialize this project

With any of the three AI tools, send this in the AI chat:

Baton init

The AI runs project-level installation and fills in missing Baton files. It does not overwrite existing project documents. A complete initialization requires a Git repository with at least one commit and a remote named origin.

You should see “project-level installation complete” or an equally clear success report. These paths should also appear in the project root:

• docs/ai_memory/
• .baton/config.json and .baton/manifest.json
• .baton/runtime/baton-closeout.mjs (managed closeout runtime)
• .baton/runtime/baton-public-update.mjs (managed public update bootstrap)
• .agents/skills/baton/, .claude/skills/baton/, and .cursor/skills/baton/
• AGENTS.md, CLAUDE.md, and .cursorrules
• .cursor/rules/baton.mdc

If the result says Git, a readable HEAD, or origin is missing, the skeleton may already be written safely, but initialization is not complete. Give the full message to the current AI and ask it to explain what is missing. Confirm the repository and its visibility yourself before the AI creates or connects a GitHub repository.

Step 6: Clock in for the first time

In the same AI chat, send:

clock in

Normally, the AI synchronizes Git, checks that no other writer is active, reads the recorded state, and shows a task table. If synchronization fails, branches diverge, changes have an unknown owner, or another writer is active, Baton stops in read-only mode and explains why. It does not overwrite code.

Baton is now installed and connected to this project.

Everyday commands

Send these commands in AI chat:

| You say | When to use it | What Baton does | |---|---|---| | Baton init | First setup, or when project entry files are missing | Restores project memory, Skills, and entry files | | clock in | Start a work session | Syncs Git, checks write ownership, reads tasks, and shows the next step | | continue work | Return after an interrupted chat | Reads the current snapshot and continues from the recorded next step | | complete task | One task is finished | Records verification evidence and waits for your acceptance | | save design spec | A page or interaction rule is confirmed | Saves the rule in project memory | | remember this pitfall | A repeated problem has been verified | Saves the pitfall and its solution | | remember this decision | A decision must be followed later | Saves the decision and its reason | | clock out | End this work session | Updates the handoff, commits, pushes, and verifies the remote SHA | | check update | Check whether Baton has an update | Checks only; it does not upgrade automatically | | update Baton | You explicitly want to update Baton | Gets the newest stable public GitHub tag and refreshes user-level and selected project files | | repair Baton | Installation or recognition fails | Reads the real error and follows the safe repair order |

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

Continue on another computer

1. On computer A, say clock out in AI chat. Confirm that the report includes commit, push, and remote SHA verification.
2. On computer B, install Git, Node.js, and PowerShell, then complete user-level Baton installation once.
3. Clone or pull your own project on computer B.
4. Open its project root with Codex, Cursor, or Claude Code.
5. Say clock in. If the AI reports that project entry files are missing, say Baton init.

Project memory and project-level entry files travel through your project's Git repository. User-level Skills belong to one computer, so install them once on every new computer.

Project files and privacy

docs/ai_memory/ stores tasks, handoffs, decisions, design rules, and pitfalls. .baton/config.json and .baton/manifest.json help restore and verify project setup. .baton/runtime/baton-closeout.mjs and .baton/runtime/baton-public-update.mjs are managed runtimes that travel with Git; they contain Baton closeout and fixed-public-update logic, not project content. These files normally go into Git with the project so different AI tools and computers can share them.

.baton/local/ belongs only to the current computer and should not be committed. Baton templates prepare ignore rules for these machine-local files.

Keep these points in mind:

• Never put API keys, tokens, passwords, or private keys in chat handoffs or project memory.
• If the project contains sensitive information, use a private Git repository that you control. Baton does not change a repository from public to private or the reverse.
• User-level installation copies Baton Skills. It does not upload your project.
• Installing or initializing Baton does not automatically change your product code.

Troubleshooting

git, node, or the script does not run

Return to Step 1 and check the versions. Do not send only the last error line. Copy the full command and complete error, give them to your AI, and say: repair Baton.

Baton init is treated like normal chat

Confirm that user-level installation completed. Fully restart the AI tool or open a new session. If it still fails, give the AI tool name, project path, and complete reply to an AI, then say: repair Baton.

Clone says the destination folder already exists

Do not keep cloning, and do not delete $HOME\Baton. Follow the True branch in Step 2. If the update fails, give the complete error to your AI.

Initialization says Git, HEAD, or origin is missing

The project cannot complete Git handoff yet. Ask the AI to explain which item is missing. You should then confirm whether to initialize Git, make a first commit, or connect a remote repository. The AI must not guess the remote address.

Cursor works, but another AI tool does not

The shared installer prepares all three tools. Fully restart the tool that cannot recognize Baton. If it still fails, ask the AI to check that tool's user-level Skill and say: repair Baton.

Do I need project-level setup for a quick test?

User-level installation teaches AI tools about Baton. Project-level setup puts memory and handoffs into a specific project. You can skip project initialization for a temporary chat, but both levels are recommended for long-running projects.

Advanced: initialize from the terminal

Use this only when you know the exact project root. The example is a runnable Windows path, but change it to your real project path first:

& "$HOME\Baton\scripts\baton-install.ps1" -Scope Project -ProjectRoot "C:\Projects\MyApp"

Run the standard public update from the project bootstrap (replace the project path first):

node "C:\Projects\MyApp\.baton\runtime\baton-public-update.mjs" --project "C:\Projects\MyApp"

If the project bootstrap is missing, use the user-level copy:

node "$HOME\.baton\runtime\baton-public-update.mjs" --project "C:\Projects\MyApp"

Both commands use only the fixed public GitHub repository. A maintainer who explicitly wants to install a local development checkout can instead request update local Baton development build; that separate flow may read $HOME\.baton\source.json and never runs as an implicit fallback.

Baton does not update in the background. It changes only after you explicitly request an update or run an update command.

Repository and license

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

Pass your project, not your context.