将任何 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 | 3.9+ |
| 唯一硬性要求 |
Claude Code | 任意 |
| 仅用于 |
pipx （推荐） | 任意 |
|
|
永远不需要第三方 Python 包——一切都在标准库上运行。
Related MCP server: Longhand
pipx install claude-handoff # or: pip install claude-handoffbrew 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会话崩溃、达到使用限制，或你关闭了终端：
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）故意不可配置——削弱删除必须是明确的每次运行选择。损坏的配置会警告并被忽略，绝不会致命。
变量 | 用途 |
|
|
|
|
|
|
| 本地 Ollama 模型和端点 |
| Claude Code 主目录（默认 |
| 块/笔记缓存目录（默认 |
| 配置文件路径（默认 |
|
|
claude-cli 不需要任何变量——它调用你安装的 Claude Code CLI，费用计入你的 Pro/Max 套餐（运行 claude 一次登录）。
任何 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 就是以此方式运行整个测试套件的）。
标志 | 含义 |
| 列出会话（日期、大小、项目、标题 · 首条提示）；如果有 |
| 选择标题/首条提示包含 QUERY 的最新会话（或网页对话） |
| 选择对话包含 TEXT 的最新会话（重复该标志以要求满足所有条件）；与 |
| 选择项目路径包含 NAME 的最新会话（可重复——多个项目一起） |
| 从编号列表中选择一个或多个会话—— |
| 忽略当前目录；考虑所有项目的会话 |
| 仅保留对话的尾部（N 轮用户消息 / 一个时间窗口） |
| 将范围内的所有会话合并为一次交接（包含会话中断标记、汇总活动） |
| 将项目的完整历史提炼到 |
| 项目记忆钩子：在 SessionStart 时注入简报，在 SessionEnd 时自动刷新事实 |
| 在每个会话结束时自动将交接写入 |
| markdown（默认）或机器可读的 JSON——也适用于 |
| 输出文件 / 标准输出 / 剪贴板（默认 |
| 通过收紧转录截断，将确定性交接调整到令牌预算（ |
| 限制转录部分的长度（默认 80 000；保留开头 + 最近的结尾） |
| 为每次工具调用添加折叠的 |
| 追加完整的子代理转录（内联侧链和 |
| 使用 LLM 总结而非原始清理后的转录 |
| 覆盖 LLM 模型 |
| 为总结添加额外指示（例如 |
| 与 |
| 为公开分享去除身份信息：主目录路径 → |
| 保留看起来像秘密的字符串（默认：从所有输出中打码，无论是否使用 LLM） |
| 禁用分块注释缓存（ |
| 作为 MCP 服务器通过 stdio 运行 |
| 与 |
| 打印 tab 补全片段 |
| 在 stderr 上报告被容忍的失败（损坏的行、不可读文件）——不会有任何内容变为致命错误 |
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
Build a clean handoff document (markdown) from a Claude Code session so another assistant can continue the work. Deterministic — no LLM calls, no cost.
| Name | Required | Description | Default |
|---|---|---|---|
| last | No | keep only the last N user turns | |
| name | No | newest session whose title or first prompt contains this | |
| path | No | explicit session .jsonl path | |
| project | No | ||
| anonymize | No | ||
| include_tools | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait ('Deterministic — no LLM calls, no cost'), which is useful, but it does not describe side effects, required session context, or how the tool processes the session beyond generating a document. This partial disclosure is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, both front-loaded with purpose and a notable trait. Every word earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, and no annotations, the description is severely under-specified. It fails to explain how parameters like anonymize or include_tools affect output, what the tool returns (file vs printed text), or any prerequisites such as an existing session. The deterministic note is helpful but does not cover the core operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the description must compensate for undocumented parameters (project, anonymize, include_tools). However, the description makes no mention of any parameters, neither explaining the documented ones nor filling gaps for the undocumented. It adds zero semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'build' and the resource 'clean handoff document (markdown) from a Claude Code session', with clear intent ('so another assistant can continue the work'). This clearly distinguishes it from sibling list_sessions, which lists sessions rather than generating documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for handoff scenarios but does not explicitly state when to use it versus list_sessions or any alternatives. It provides context for its purpose but lacks explicit exclusions or comparisons, leaving the agent to infer the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Claude Code sessions on this machine, newest first: date, project, id, title and first prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | substring filter on the project path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the read-only nature implicitly (listing) and the ordering, but it doesn't explicitly state that no modifications occur, nor does it mention any authentication requirements or potential limitations. The description is adequate but not rich in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, directly front-loaded sentence states the resource, ordering, and return fields without any fluff or repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the essential return fields and ordering. It omits details like pagination limits or how many sessions are returned, but for a straightforward listing operation this is a minor gap given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage for the single parameter 'project' is 100%, with a clear description of it being a substring filter on the project path. The tool description adds no additional parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('Claude Code sessions on this machine'), and the behavior ('newest first'), plus the fields included. It's easily distinguished from the lone sibling 'handoff', which implies a different purpose entirely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing local sessions, but provides no explicit when-to-use or when-not-to-use guidance, nor does it reference any alternatives. With only one sibling (handoff) that seems unrelated, the context is adequate but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0handofflist_sessionsScored across 2 tools
The two tools have clearly distinct purposes: one lists available sessions and the other generates a handoff document from a selected session. There is no overlap or ambiguity in their roles.
Both tool names are concise verbs, but they mix patterns slightly: 'list_sessions' follows verb_noun while 'handoff' is a single verb/noun. The inconsistency is minor and both names are predictable in context.
Two tools is a thin set, but it matches the server's narrow purpose of session listing and handoff generation. It feels borderline but acceptable for a focused utility.
The domain is fully covered: list_sessions provides the discovery step and handoff provides the output generation. There are no obvious dead ends or missing operations for the stated purpose.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
