baton

---

下午 4 点的难题

下午 4 点，Claude Code 提示 “已达到使用上限 — 晚上 10 点重置。” 你已经投入三个小时：确定了架构，梳理了边缘情况，还写完了一半的代码差异。

❌ 不使用 baton — 打开另一个 Agent，从头开始。重新解释计划，重新阅读文件，重新讨论所有已经做出的决定。

✅ 使用 baton — 传递会话，接着继续：

baton convert --from claude-code --to opencode --latest --import
# using latest claude-code session: 2026-07-09 15:58  Refactor the auth middleware to…
# passed baton: claude-code → opencode (1388 messages) → handoff.json
# Imported session: ses_8c4c973a521549e2

opencode -s ses_8c4c973a521549e2   # same conversation, different runner

支持任意方向切换：在任务进行中切换 Agent、针对棘手的 bug 征求第二种意见、将会话从编辑器 Agent 转移到终端 Agent，或将所有内容归档为一种格式。

快速开始

# zero-install run (downloads prebuilt binary)
npx @kasabeh/baton-mcp --help

# convert your most recent session + auto-import into the target agent
baton convert --from claude-code --to opencode --latest --import

# or omit the path to pick interactively — newest first,
# each session previewed by its first user message
baton convert --from claude-code --to opencode --import

# or pass an explicit session file
baton convert --from claude-code --to opencode <session.jsonl> --import

# see every session on your machine, across all agents
baton list

会话文件存放在哪里？

你无需费力查找这些文件（--latest 和交互式选择器会帮你找到），但供你参考 — 每个 Agent 都会将对话记录存储在磁盘上：

Agent	位置
Claude Code	~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
Codex CLI	~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl

baton list 会列出它能找到的所有 Agent 会话的路径。

支持的格式

Agent	读取	写入	自动导入
Claude Code	✅	✅	—
OpenCode	✅	✅	✅ opencode import
Codex CLI	✅	✅	—
Gemini CLI	✅	✅	—
Zed	✅	✅	—
Aider	✅	✅	—
Cursor	✅¹	—²	—
Continue	✅	—	—
Cline / Roo	✅	—²	—

¹ Cursor 从导出的 JSON 读取（sqlite3 state.vscdb "SELECT value FROM ItemTable WHERE key='aiService:chats'"）

² 暂不计划支持：Cursor 和 Cline 会将会话状态保存在编辑器数据库中（SQLite / VS Code globalState），没有基于文件的导入路径。

基准测试

将完整对话记录传递给下一个 Agent，效果是否优于编写交接摘要？我们在一个真实的 3.4 MB Claude Code 会话上对两种方式进行了测量（两组使用相同模型，只有上下文不同）：

会话大小	baton 对话记录	交接摘要
sm (93 KB)	回忆起 3/3 条细节	1/3
md (198 KB)	6/6	1/6
lg (599 KB)	5/8	1/8
总计	14/17	3/17

即使在最小的片段中，摘要也遗漏了具体事实（版本、行数、MSRV）——接收方 Agent 不得不重新阅读文件并重跑命令，才能找回这些信息。机械保真度：所有 896 条消息都会写入每种目标格式；往返转换造成的信息丢失，反映了各目标格式的表达能力（claude-code 896/896、codex 736、gemini-cli 723、aider 111 — 它只保存聊天文本）。

我们还测量了任务延续能力：在三个任务进行到一半的节点截断会话，让一个全新的 Agent 说明任务、当前状态和下一步。结果持平（baton 10/12，交接摘要 10/12）——一份好的摘要足以说明下一步做什么；而对摘要撰写者未预料到的具体事实问题，只有对话记录才能作答。此外，只有 Agent 花时间完整阅读对话记录并撰写摘要，摘要才会存在 — baton 则让传递过程不费吹灰之力。

完整的方法说明、注意事项和复现步骤：benchmark/RESULTS.md。

MCP 服务

baton 也是一个 MCP 服务——你的 Agent 可以在对话过程中直接传递 baton：

工具	描述
list_sessions	扫描所有 Agent，并返回统一列表
convert_session	将会话从一种格式转换为另一种格式
import_to_target	转换会话，并运行目标 Agent 的导入命令
detect_format	检查文件或目录，并报告其由哪个 Agent 生成

baton install     # registers baton in every detected agent's MCP config
baton doctor      # verify
baton uninstall   # remove from all agents

工作原理

Claude Code session (.jsonl)
      │
      ▼
  baton read ──► canonical Session { messages: [Text, Reasoning, ToolCall, ToolResult] }
      │
      ▼
  baton write ──► OpenCode import JSON (SessionV1 schema)

每种 Agent 格式都会先读入规范化中间表示，再写出为目标格式。添加一种新格式的复杂度为 O(1)，而不是为每一对格式编写转换器所需的 O(N×M)。

安装

# npm (prebuilt binary, no Rust needed)
npm install -g @kasabeh/baton-mcp

# Homebrew
brew install kaseban/tap/baton-mcp

# Cargo binstall (prebuilt binary)
cargo binstall baton-mcp

# Cargo (from source)
cargo install baton-mcp

# Shell installer (prebuilt binary)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Kaseban/baton/releases/latest/download/baton-mcp-installer.sh | sh

或者从 GitHub Releases 获取二进制文件。

构建

git clone https://github.com/Kaseban/baton.git
cd baton
cargo build --release
./target/release/baton --help

贡献

每种格式都位于 src/formats/<name>.rs 中，并实现 Format 特征（读取 + 写入）。完整的参考实现请参见 src/formats/claude_code.rs。

所有九种格式都有读取器；Claude Code、OpenCode、Codex、Zed、Aider 和 Gemini CLI 也有写入器。目前最有价值的贡献是为 Continue 编写写入器。

重新生成演示

README 中的 GIF 使用 VHS 脚本生成：vhs assets/demo.tape。它会在沙盒化的 $HOME（/tmp/demo）中录制，该目录填充了虚构会话，因此 GIF 中不会出现任何真实会话数据。

不要放下 baton。

许可证

采用 MIT 或 Apache-2.0 双重许可。