claude-handoff

将任何 Claude Code 会话——即使是崩溃的会话——变成一份干净的 handoff.md，让另一个 AI 可以继续。并给 Claude Code 永久项目记忆，从你自己的历史中提炼。

chf

就是这样。你最近的会话变成 handoff.md：去除噪音的对话、变更的文件、运行的命令——开头是给接收助手的指令，这样你可以直接粘贴到 Gemini、GPT、claude.ai 或全新的 Claude Code 会话中，无需任何额外提示。

Claude Code 将每个会话本地存储为 JSONL（~/.claude/projects/…/*.jsonl），其中充满工具调用、工具结果、思考块和系统提醒。现有的导出器会把所有这些转储为 markdown。claude-handoff 则生成一份 handoff 文档——而且，由于它能读取你的全部历史，还能生成一份项目记忆简报。

• 零依赖。 仅标准库，Python 3.9+。一个九模块的包——也以生成的单文件脚本形式提供，你可以 curl 并审计。

• 默认确定性。 无 API 调用，无成本，离线可用。

• 需要真正摘要时使用 --llm。 通过你自己的 API 密钥使用 Claude、OpenAI 或 Gemini——或者 --llm claude-cli，它在你现有的 Pro/Max 套餐上运行你本地安装的 Claude Code CLI：完全不需要 API 密钥。

• 无噪音。 丢弃工具结果、思考块、系统提醒、子代理闲聊、斜杠命令包装。保留用户意图、助手回答、修改的文件、运行的命令——包括子代理（agent-*.jsonl）的文件和命令，其完整转录保留在 --include-sidechains 之后。

• 项目记忆。 chf --brief 将项目的整个会话历史提炼成一份活的简报（决策、修复、约定、未决线程——附会话引用）；--install-brief-hook 将其注入每个新的 Claude Code 会话，让 Claude 一开始就了解项目。

• 可安全粘贴。 类似秘密的字符串（API 密钥、令牌、password=…）会从每个输出中删除——你粘贴到网页聊天中的 handoff 也是出口。--anonymize 进一步适用于公开分享。

先决条件

永远不需要第三方 Python 包——一切都在标准库上运行。

Related MCP server: Longhand

安装

pipx install claude-handoff        # or: pip install claude-handoff

brew install Vasilispapg/tap/claude-handoff   # Homebrew

# or just grab the generated single-file build — stdlib-only, auditable:
curl -O https://raw.githubusercontent.com/Vasilispapg/claude-handoff/main/single/claude_handoff.py
python3 claude_handoff.py --list

安装该包会给你两个相同的命令：claude-handoff 和短别名 chf。Tab 补全：

eval "$(claude-handoff --completions zsh)"    # bash works too

60 秒：选择你的情况

会话崩溃、达到使用限制，或你关闭了终端：

chf -o clipboard

…然后粘贴到 claude.ai、ChatGPT、Gemini——或一个新的 claude 会话。适用于任何旧会话；崩溃之前无需安装任何东西。

将工作从 Claude Code 转移到另一个模型：

chf --fit 32k -o clipboard         # sized to the receiver's context window

“我们讨论 CORS 的是哪个会话？”

chf --list --grep "CORS"           # every match, with a 🔍 context preview
chf --grep "CORS"                  # or export the newest match directly

给 Claude Code 这个项目的永久记忆：

chf --brief --llm claude-cli       # distill ALL sessions → one cited brief
chf --install-brief-hook           # every new session starts knowing it

真正的摘要而不是转录（目标 / 决策 / 状态 / 下一步）：

chf --llm claude-cli               # your Claude Code login — no API key

一个 claude.ai 或 ChatGPT 网页聊天而不是终端会话：

chf conversations.json --list      # each app's data export works as input
chf conversations.json --name "webhook bug"

项目记忆（--brief）

Claude Code 在会话之间会忘记一切——但整个历史都在你的磁盘上。chf --brief 读取当前项目的每个会话，并将一份记忆文档写入 ~/.claude/briefs/<project>.md：

• 一个事实性的会话时间线 + 最常触碰的文件（确定性，免费）；

• 使用 --llm 时，一份提炼的记忆——决策及其原因、修复的 bug、约定、未决线程——每个要点都附有来源会话 id（chf --name <id> 打开源）。

每个会话的笔记会被缓存，因此新会话后刷新只需为新会话付费——而一个巨大的会话（超过 ~120k 字符）会在笔记内部进行 map-reduce，因此记忆路径永远不会截断：任何大小都不会静默丢弃。

chf --install-brief-hook

安装两个钩子：SessionStart 将简报作为上下文注入（Claude 一开始就了解你的项目——/compact 后也会重新注入），SessionEnd 免费自动刷新事实部分。钩子永远不会运行 LLM；提炼部分只在你明确要求时刷新。简报带有新鲜度戳，文件和注入都会在新会话存在时发出警告。完全本地；删除操作适用于所有地方。

→ 逐步机制、诚实的成本表，以及完整的一天使用演练：docs/GUIDE.md。

使其自动化

chf --install-hook                 # SessionEnd + PreCompact → handoff to ~/.claude/handoffs/
chf --install-brief-hook           # SessionStart/End + PreCompact → project memory (above)

PreCompact 很重要：就在 Claude Code 压缩长会话上下文之前，两个钩子都会快照状态——handoff 保留了压缩即将挤掉的细节，简报骨架在会话中保持新鲜。

两者都以非破坏性方式编辑 ~/.claude/settings.json，是幂等的，并有对应的 --uninstall-* 标志。钩子失败永远不会破坏宿主会话，钩子也永远不会触发 LLM 调用或自行创建文件。

输出看起来什么样

# Conversation handoff

> To the receiving assistant: … you are taking over …

## Session
- Project: /home/you/myapp (branch main)
- When: 2026-08-20 09:00 → 09:04
- Activity: 2 user messages, 4 assistant replies, 4 tool calls

## Files created / modified
- /home/you/myapp/auth.py

## Commands run
- python -m pytest tests/test_auth.py -q

_🤖 2 subagent(s) contributed to the work above (--include-sidechains for their transcripts)._

## Conversation
### 🧑 User
the login breaks on unicode passwords…
### 🤖 Assistant
Found it — ascii encoding. Changed to utf-8, tests pass.

常用命令

chf                                # latest session → handoff.md
chf -i                             # numbered picker; "1,3" or "2-4" merges several
chf --list                         # what sessions do I have? (title · first prompt)
chf --list --format json           # the same, machine-readable
chf --name "login bug"             # newest session whose title/prompt matches
chf "login bug"                    # same — a non-path argument is a name search
chf --grep "CORS"                  # newest session that *talked about* CORS
chf --grep CORS --grep auth        # …that talked about BOTH (AND)
chf a.jsonl b.jsonl                # several paths → ONE merged handoff
chf --project myrepo               # latest session of a specific project
chf path/to/session.jsonl -o -     # explicit file → stdout
chf -o clipboard                   # straight to the clipboard — go paste it
chf --last 5                       # only the last 5 user turns
chf --since 2h                     # only the last 2 hours of the session
chf --fit 32k                      # sized to fit a 32k-token context
chf --include-tools                # keep collapsed per-tool-call detail
chf --include-sidechains           # append full subagent transcripts
chf --anonymize                    # public-safe: ~ paths, no emails/IPs/username
chf --project myrepo --merge       # whole project in ONE handoff, oldest → newest
chf --format json -o session.json  # machine-readable handoff

# LLM summaries (goal / decisions / current state / next steps):
chf --llm claude-cli               # your Claude Code login — no API key
chf --llm ollama                   # local model — fully offline
chf --llm claude                   # Anthropic API   (ANTHROPIC_API_KEY)
chf --llm openai --model gpt-4o    # OpenAI API      (OPENAI_API_KEY)
chf --llm gemini --with-transcript # Google API      (GEMINI_API_KEY)
chf --llm claude-cli --focus "emphasize the API decisions"

# project memory:
chf --brief                        # free factual brief (timeline + files)
chf --brief --llm claude-cli       # + distilled decisions/fixes/conventions

它在哪里查找？ 会话位于 Claude Code 的全局存储中（~/.claude/projects），因此你可以从任何地方运行 chf。如果你当前目录是一个项目（或项目的子文件夹），它会限定到该项目的会话；父“主文件夹”限定到其下所有项目；--any 完全忽略目录。自动选择会跳过几乎为空的会话（比如 claude /login 留下的存根），因此“最新”意味着你最近的真实对话——显式路径、--name 或 -i 始终优先。

大会话。 超过一次传递（~400k 字符）的转录以 map-reduce 方式总结：每个块做笔记，然后一次综合——不会静默丢弃任何内容，完成的块缓存在 ~/.cache/claude-handoff 中，因此中断的运行可以免费恢复。块在 API 提供商上以 4 路并行运行；claude-cli 和 ollama 按设计保持顺序。在终端中你会看到实时进度条：

[█████████░░░░░░░░░░░░░░░] 3/9 chunks | 4m12s elapsed | ~8m left | summarizing part 4/8 (199,867 chars)…

带有 API usage 数据的会话还会在头部获得 Tokens 行，每次运行都会报告输出的 ≈token 大小。

隐私与零信任

• 除非你传递 --llm，否则不会向任何地方发送任何内容——确定性模式完全离线。

• 删除操作对每个输出都开启，而不仅仅是 LLM 流量：类似秘密的字符串（API 密钥、令牌、JWT、password=…）会从 handoff 本身、钩子文件和 MCP 回复中剥离——粘贴的文档也是出口。--no-redact 每次运行选择退出（并且故意不允许在配置文件中）。

• --anonymize 额外将你的主目录折叠为 ~，并用占位符替换电子邮件、IPv4 和你的用户名——用于粘贴到公共问题和论坛。

• --llm claude-cli 和 --llm ollama 将一切保持在你已经控制的账户和机器内。

• 提示注入防御：转录经常嵌入不可信文本（工具结果中的网页、粘贴的 README）。每个消费转录的提示、handoff 前言和简报注入包装都将该内容框定为数据，而非指令——由测试固定。这是一种缓解措施，而非证明；解析器本身从不执行任何内容。

配置（可选）

将你总是使用的默认值放在 ~/.config/claude-handoff/config.json 中（CLI 标志始终优先；CLAUDE_HANDOFF_CONFIG 覆盖路径）：

{ "llm": "claude-cli", "fit": "32k", "include_tools": true }

允许的键：llm、model、fit、output、include_tools、include_sidechains、max_chars、anonymize、focus。安全开关（no_redact）故意不可配置——削弱删除必须是明确的每次运行选择。损坏的配置会警告并被忽略，绝不会致命。

环境变量

claude-cli 不需要任何变量——它调用你安装的 Claude Code CLI，费用计入你的 Pro/Max 套餐（运行 claude 一次登录）。

MCP 服务器

任何 MCP 客户端（Claude Desktop、Claude Code、…）都可以直接拉取 handoff：

claude mcp add claude-handoff -- claude-handoff --mcp

工具：list_sessions（这台机器上有什么）和 handoff（按名称/项目/路径为会话构建文档；传递 anonymize 获取可分享版本）。默认确定性——MCP 客户端只能在你以 --allow-llm 启动服务器时触发 LLM 摘要。

故障排除

pip install 后 claude-handoff: command not found pip 将脚本放在可能不在 PATH 中的用户 bin 目录。使用 pipx install claude-handoff 或 brew——两者都管理 PATH——或将 ~/.local/bin（Linux）/ ~/Library/Python/3.x/bin（macOS）添加到你的 PATH。

“在 ~/.claude/projects 下未找到会话” 你在一台尚未运行 Claude Code 的机器（或用户）上，或者你的存储在其他地方——将 CLAUDE_HOME 指向它。在项目文件夹内，工具限定到该项目；传递 --any 搜索所有内容。

它选错了会话 “最新”会跳过几乎为空的存根，但仍然只是最新的文件。使用 -i（选择器）、--name "标题的一部分" 或 --grep "说过的内容"。

--llm claude-cli 失败或要求登录 先运行一次 claude 并登录（/login）。即使在 Claude Code 会话内部调用也能正常工作——继承的 CLAUDE* 环境变量会被清除，因此嵌套 CLI 会像全新会话一样进行身份验证。

"设置 ANTHROPIC_API_KEY … 以使用 --llm claude" API 提供商需要在环境中设置密钥——请参阅上表。完全没有密钥？请使用 --llm claude-cli（订阅）或 --llm ollama（本地）。

--fit 拒绝与 --llm / --max-chars 组合使用 --fit 会自行调整确定性输出的大小。如果你没有输入该参数，可能是配置文件设置了 fit——请用显式的 --max-chars 覆盖，或删除该键。

简短简报注入警告"存在比此简报更新的会话" 这是新鲜度标记在发挥作用：运行 chf --brief --llm claude-cli 重新提炼（有缓存——只有新会话需要付费）。如果安装了 SessionEnd 钩子，事实部分会自动刷新。

某些操作静默无效？ 容错设计路径（损坏的 JSONL 行、不可读文件、缓存问题）绝不会导致运行崩溃——添加 --debug（或 CLAUDE_HANDOFF_DEBUG=1）查看具体跳过了什么及原因。钩子始终在 stderr 上报告错误，同时仍以 0 退出。

Windows 上出现乱码 设置 PYTHONUTF8=1（CI 就是以此方式运行整个测试套件的）。

完整参数参考

路线图

• Gemini 导出作为输入（Google Takeout 仅提供 HTML——需要提供真实的、经脱敏的导出用于构建）

• 会话链：自动检测 /compact 延续的会话，并提供合并谱系的选项（--follow）

欢迎提交 PR。

对比

这个领域并非空白——而是碎片化的。选择适合你情况的工具：

• 导出工具 — claude-conversation-extractor、claude-code-log、claude-code-transcripts、claude-to-markdown — 将转录转为可读的 Markdown/HTML，包含工具噪音，没有交接框架。

• 跨 CLI 会话迁移工具 — cli-continues（npm i -g continues）读取 16 种编码 CLI 的原生会话存储（包括 Claude Code），并将上下文文档注入另一个终端工具。非常适合 Claude Code → Codex/Cursor/Gemini CLI；但无法针对网页聊天，不做 LLM 总结，且需要 Node 22.5+。

• 会话内交接技能/插件 — thepushkarp/handoff、claude-session-handoff、claude-code-handoff — 前提是你记得在会话结束前运行它们；模型使用你当前会话的上下文编写总结，输出面向下一个 Claude 会话。

• 浏览器扩展 — Handoff、LLM Context Bridge、ContextSwitch — 在 ChatGPT/Claude/Gemini 之间转移网页聊天；它们无法查看 Claude Code 会话。

claude-handoff 是这个版图的事后、随处粘贴的角落：它在事后处理 JSONL——旧会话、崩溃的会话、达到使用限制的会话——无需预先安装任何东西，默认零令牌成本，可以在你要求时写出真正的中文总结（--llm），并生成任何接收模型都能接手的文档，包括浏览器或手机上的 claude.ai、ChatGPT 和 Gemini。而且通过 --brief，它是唯一能将历史转化为持久项目记忆的工具。

开发

git clone https://github.com/Vasilispapg/claude-handoff && cd claude-handoff
python3 -m unittest discover -s tests -v      # the whole suite (no deps needed)
python3 -m claude_handoff tests/fixtures/agent_session.jsonl -o -   # smoke run
python3 scripts/build_single.py --check       # single-file build is fresh
uvx ruff check claude_handoff scripts tests   # lint (config in pyproject)

运行时代码位于 claude_handoff/ 包中；single/claude_handoff.py 是生成的——任何包变更后使用 python3 scripts/build_single.py 重建（过时时 CI 会失败）。新的解析器行为从 tests/fixtures/ 中的脱敏测试夹具开始——请参阅 CONTRIBUTING.md 和 AGENTS.md（面向人类和 AI 贡献者的说明与不变量）。

了解更多

docs/GUIDE.md — 与 claude-handoff 共度一天：走查、--brief 逐步工作原理、诚实成本表、速查表 · INDEX.md — 文件地图 · docs/DEVELOPMENT.md — 架构、JSONL 模式说明、设计决策 · AGENTS.md — 面向 AI 编码代理的贡献者指南 · CONTRIBUTING.md · CHANGELOG.md

许可证

MIT

mcp-name: io.github.Vasilispapg/claude-handoff