claude-handoff

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 则会生成交接文档；此外，由于它可以读取你的全部历史记录，还能生成项目记忆简报。

• 零依赖。 仅使用标准库，支持 Python 3.9+。这是一个包含九个模块的包，也提供生成的单文件脚本，可供你通过 curl 下载并审查。
• 默认行为可预测。 无需 API 调用，不产生费用，可离线使用。
• 需要真正的摘要时，可使用 --llm。 通过你自己的 API 密钥使用 Claude、OpenAI 或 Gemini；也可以使用 --llm claude-cli，通过你现有的 Pro/Max 套餐运行本机安装的 Claude Code CLI：完全无需 API 密钥。
• 去除杂音。 丢弃工具结果、思考区块、系统提醒、子 Agent 对话和斜杠命令封装。保留用户意图、助手回答、修改的文件和运行的命令——包括子 Agent 的文件和命令（agent-*.jsonl）；子 Agent 的完整对话记录则由 --include-sidechains 保留。
• 项目记忆。 chf --brief 会将项目的全部会话历史提炼成一份持续更新的简报，涵盖项目内容、当前进展、决策、修复、约定，以及按顺序排列的未完成事项恢复计划；每项内容均注明来源会话。使用 --install-brief-hook 将其注入每个新的 Claude Code 会话，让 Claude 一开始就了解项目。
• 粘贴安全。 所有输出中的疑似机密字符串（API 密钥、令牌、password= 等）都会被删去——粘贴到网页聊天中的交接文档同样属于数据外发。公开分享时，--anonymize 可进行更彻底的匿名化。

---

前置条件

要求	最低要求	检查命令	说明
Python	3.9+	python3 --version	唯一的硬性要求
Claude Code	任意版本	claude --version	仅供 --llm claude-cli 使用（使用你的 Pro/Max 登录）
pipx (推荐)	任意版本	pipx --version	使用 pip install pipx 安装，也可以使用 brew / 普通 pip

永远不需要第三方 Python 包——所有功能都通过标准库实现。

安装

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、约定，以及按顺序排列的待处理事项恢复计划。每项都包含具体的下一步操作，并标记 [in flight] / [blocked] / [not started]。每条要点都会注明其来源会话的 ID（chf --name <id> 可打开来源）。

每个会话的笔记都会缓存，因此有新会话后刷新时只需处理新增内容；超长会话（超过约 120k 个字符）会在笔记内部进行映射归约，因此记忆路径永远不会被截断：无论内容多长，都不会被悄悄丢弃。

你还可以筛选哪些内容会纳入记忆：--exclude <id> 可排除一个会话（例如重复内容或实验会话——单独使用 --exclude 会打开带编号的选择器，并记住之前的选择：已存储的排除项会预先选中并显示为 ✗，输入编号可切换选择，因此你修改的是当前集合，而不是重新选择）；--keep first:2,last:20 可将庞大的历史记录限制为最初的会话，加上一个滑动的近期会话窗口。两者都会持续生效——设置会存储在 brief 的标记中，因此钩子和后续刷新都会继续遵循这些设置，直到你更改它们（--exclude none、--keep all）。chf --brief -o clipboard 还可以将当前 brief（包括提炼内容）直接复制到剪贴板，只需粘贴一次，即可将项目记忆交给另一个模型。

brief 还支持项目存储之外的内容：chf --brief --grep X -o - 可提炼主题记忆（仅包含讨论过 X 的会话）；chf conversations.json --brief -o brief.md 则可从 claude.ai 或 ChatGPT 导出文件构建常驻记忆，并为每段对话标注其 ID。两者都设计为导出操作（仅显式指定 -o 时才会导出），因此绝不会覆盖常驻 brief。

如果你正在运行 graphify，这两个工具可以双向组合，无需配置：chf --brief -o graphify 会将当前记忆存入 raw/——形成一份不断演进的 project-memory.md，供下一次 /graphify --update 链接到代码知识图谱中；而一旦 graphify-out/graph.json 存在，每份 brief 都会免费附带一个 ## Code map（社区、枢纽概念、跨社区的 bridges:、带标签的 flows:），让新会话了解代码的结构，而不仅仅是它的历史。项目内副本（raw/project-memory.md、可选的根目录 BRIEF.md）会在每次写入 brief 时刷新——严格来说只刷新已有文件，钩子绝不会创建文件。完整流程请参阅 docs/GUIDE.md。

chf --install-brief-hook

会安装两个钩子：SessionStart 会将 brief 注入上下文（Claude 启动时就已了解你的项目，执行 /compact 后也会再次注入）；SessionEnd 会免费自动刷新事实性内容。钩子绝不会运行 LLM；只有在你主动要求时，才会刷新提炼后的内容。brief 会附带新鲜度标记；如果存在更新的会话或提交，文件和注入内容不只会发出警告，还会列出具体内容（会话标题、提交主题），因此新会话能看到具体变更，而不只是知道有变更。完全在本地运行；与其他所有地方一样，适用脱敏规则。

→ 分步说明工作机制、如实列出的成本表，以及完整的一日使用流程：docs/GUIDE.md。

自动完成

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

PreCompact 很重要：Claude Code 即将压缩长会话的上下文时，两个钩子都会立即快照状态——交接内容保留了压缩即将挤掉的细节，而简要提纲则能在会话中途保持最新。

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

第三个是给 Claude 本身用的：--install-skill 会将 /claude-handoff 技能放入 ~/.claude/skills/（并在 ~/.claude/CLAUDE.md 中添加相应的触发说明），让 Claude Code 知道该工具的语法，而不是靠猜测——例如在实时会话中，裸用 chf 会选择哪个会话、claude-cli（订阅）与 claude（API 密钥）的区别、用于适配令牌预算的 --fit，以及避免在 Agent shell 中使用交互式选择器。此操作具有幂等性，会保留手写的章节；--uninstall-skill 会移除这两部分，且不会改动任一文件中的其他内容。

---

输出示例

# 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, 2 assistant replies, 4 tool calls

## Files created / modified
- 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

_Condensed digest, every turn capped — verbatim messages with --full, a real summary with --llm._

- **🧑 User:** the login breaks on unicode passwords…
- **🤖 Assistant:** Found it — ascii encoding. Changed to utf-8, tests pass. _[4 tool calls]_
- 🔔 Agent "Update the docs" finished

这里包含每一轮对话，并压缩为其要点——这是一个摘要工具，而不是导出工具。--full 会切换到经典的逐字消息模式，而 --llm 会用真正读完所有内容后生成的摘要替换简报。

常用命令

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 --full                         # verbatim messages instead of the digest
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).
# --llm composes with EVERYTHING above — picker, --name/--grep/--project,
# --merge, --last/--since, clipboard, JSON… (only --fit stays
# deterministic-only, by design):
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"
chf --grep CORS --llm claude-cli   # find the session, then summarize it
chf -i --merge --llm claude-cli -o clipboard   # pick several → ONE summary, pasted
chf --since 2h --llm claude-cli    # summarize just the last two hours

# project memory:
chf --brief                        # free factual brief (timeline + files)
chf --brief --llm claude-cli       # + distilled decisions/fixes/conventions
chf --brief --exclude              # numbered picker: edit the sticky exclusions (✗ pre-selected, numbers toggle)
chf --brief --keep first:2,last:20 # bound a huge history: founding + recent
chf --brief --keep since:30d       # …or by time — the window slides
chf --brief --grep auth -o -       # thematic memory: only the auth sessions
chf conversations.json --brief -o brief.md   # memory from a claude.ai/ChatGPT export

它会在哪里查找？ 会话存储在 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 行，每次运行还会报告输出的大致令牌数。

隐私与零信任

• 除非你传入 --llm，否则不会向任何地方发送数据——确定性模式完全离线。
• 所有输出都会进行脱敏，不仅限于 LLM 流量：形似机密的字符串（API 密钥、令牌、JWT、password= 等）都会从交接内容、钩子文件和 MCP 回复中删除——粘贴的文档也属于数据外传。使用 --no-redact 可在单次运行中选择退出（且有意禁止在配置文件中使用）。
• --anonymize 还会将你的主目录路径统一替换为 ~，并将电子邮箱、IPv4 地址和用户名替换为占位符——方便粘贴到公开问题和论坛中。
• --llm claude-cli 和 --llm ollama 会将所有内容保留在你已掌控的账户和设备内。
• 提示词注入防御：文字记录中经常嵌入不可信文本（工具结果中的网页、粘贴的 README）。所有会读取文字记录的提示词、交接前言和简报注入包装都会将这些内容标明为数据，而非指令——并通过测试加以验证。这是一种缓解措施，而非安全性证明；解析器本身不会执行任何内容。

配置（可选）

将你总是使用的默认值写入 ~/.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）有意不设为可配置项——必须通过每次运行时的显式选择才能削弱脱敏。配置损坏时会发出警告并忽略，不会导致程序失败。

环境变量

变量	用途
ANTHROPIC_API_KEY / CLAUDE_API	--llm claude 的密钥（优先使用第一个已设置的变量）
OPENAI_API_KEY / GPT_API	--llm openai 的密钥
GEMINI_API_KEY / GOOGLE_API_KEY / GEMINI_API	--llm gemini 的密钥
OLLAMA_MODEL / OLLAMA_BASE_URL	本地 Ollama 模型和端点
CLAUDE_HOME	Claude Code 主目录（默认 ~/.claude）——会话、交接文档和摘要的存放位置
CLAUDE_HANDOFF_CACHE	分块/笔记缓存目录（默认 ~/.cache/claude-handoff）
CLAUDE_HANDOFF_CONFIG	配置文件路径（默认 ~/.config/claude-handoff/config.json）
CLAUDE_HANDOFF_DEBUG	1 = 等同于 --debug；同时启用钩子（将其添加到钩子命令或 shell 环境中）

claude-cli 无需设置变量——它会调用已安装的 Claude Code CLI，费用计入你的 Pro/Max 计划 （运行一次 claude 即可登录）。

MCP 服务

任何 MCP 客户端（Claude Desktop、Claude Code 等）都可以直接获取交接文档：

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

工具：list_sessions（查看此机器上的内容）和 handoff（按名称/项目/路径为会话生成文档；传入 anonymize 可生成可分享的版本）。默认采用确定性方式——只有在启动服务时添加 --allow-llm，MCP 客户端才能触发 LLM 摘要。

故障排除

运行 pip install 后提示 claude-handoff: command not found pip 会将脚本安装到用户的 bin 目录，该目录可能不在 PATH 中。使用 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 会像全新启动一样进行身份验证。

--llm claude-cli 失败并提示“Credit balance is too low” 你在 shell 中导出的 ANTHROPIC_API_KEY 覆盖了 Pro/Max 登录信息，并向（余额为零的）Console 账户计费。从 0.18.0 起，启动的 CLI 会自动清除此密钥——如果旧版本出现此问题，请升级，或在运行前执行 unset ANTHROPIC_API_KEY。

提示“设置 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 运行整个测试套件时也使用此设置）。

完整标志参考

标志	含义
--list	列出会话（日期、大小、项目、标题 · 首条提示词）；如果提供 conversations.json，则列出其中的聊天
--name QUERY	选择标题或首条提示词中包含 QUERY 的最新会话（或网页对话）
--grep TEXT	选择对话中包含 TEXT 的最新会话（重复此标志可要求包含所有词项）；与 --list/-i 搭配时，显示每个匹配项及 🔍 预览
--project NAME	选择项目路径中包含 NAME 的最新会话（可重复使用，合并多个项目）
-i / --interactive	从编号列表中选择会话 — 1,3 或 2-4 可将多个会话合并为一个交接记录
--any	忽略当前目录；考虑所有项目的会话
--last N / --since 2h	仅保留对话的末尾部分（N 轮用户发言 / 一个时间范围）
--merge	将范围内的所有会话合并为一个交接记录（含会话分隔标记、汇总活动）
--brief	将项目的完整历史提炼到 ~/.claude/briefs/<project>.md（确定性生成；使用 --llm 进行实际提炼）
--exclude ID	与 --brief 搭配时：将会话排除在记忆之外 — 使用 ID 前缀（来自 --list 或简报的引用），多个 ID 用逗号分隔或重复此标志；单独使用 --exclude 会打开编号选择器，并预选已保存的集合（✗）— 输入编号可切换，留空则保留，输入 none 则清除；刷新后仍生效，使用 --exclude none 可清除
--keep SPEC	与 --brief 搭配时：限定用于生成记忆的会话范围 — 20 / last:20（最近会话）、first:2（最早的会话）、since:7d（按最近活动时间；也可使用 ISO 日期），或 first:2,since:30d 这样的组合；会持续生效，因此刷新时会保留一个滑动窗口；使用 --keep all 可清除
--install-brief-hook / --uninstall-brief-hook	项目记忆钩子：在 SessionStart 时注入简报，在 SessionEnd 时自动刷新事实
--install-hook / --uninstall-hook	每次会话结束时，自动将交接记录写入 ~/.claude/handoffs/
--install-skill / --uninstall-skill	安装 /claude-handoff Claude Code 技能（~/.claude/skills/ 下的 SKILL.md + ~/.claude/CLAUDE.md 中的触发器部分），以便 Claude 正确使用 chf — 可重复执行，尊重手写部分，卸载时保留 CLAUDE.md 的其他内容
--format md|json	Markdown（默认）或机器可读的 JSON — 也适用于 --list
-o FILE / -o - / -o clipboard / -o graphify	输出到文件 / 标准输出 / 剪贴板 / graphify 语料库（raw/，用于知识图谱）；默认值为 handoff.md
--fit TOKENS	通过收紧转录截断范围，将确定性生成的交接记录调整为符合令牌预算（32k、128k、1m）
--full	使用逐字记录的对话轮次（经典转录），而非默认的精简摘要
--max-chars N	限制转录部分的字符数（默认 80 000；保留开头和最近的结尾）
--include-tools	使用折叠的 <details> 块展示每次工具调用
--include-sidechains	附加完整的子 Agent 转录（内联支线对话和 <session-id>/subagents/agent-*.jsonl）；其文件/命令活动始终计入统计
--llm claude|openai|gemini|claude-cli|ollama	使用大模型摘要，而非未经处理的清理后转录
--model ID	覆盖大模型
--focus TEXT	为摘要添加额外指示（例如 --focus "emphasize the API decisions"）
--with-transcript	与 --llm 搭配时，也附加清理后的转录
--anonymize	去除身份信息以便公开分享：将主目录路径替换为 ~，将电子邮件地址/IP 地址/用户名替换为占位符
--no-redact	保留看起来像机密的字符串（默认情况下，所有输出都会进行脱敏，无论是否使用大模型）
--no-cache	禁用分块笔记缓存（~/.cache/claude-handoff）
--mcp	通过标准输入/输出以 MCP 服务模式运行
--allow-llm	与 --mcp 搭配时：允许 handoff 工具运行大模型摘要（需明确启用）
--completions bash|zsh	打印制表符补全代码片段
--debug	将已容忍的故障（损坏的行、无法读取的文件）报告到 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；但无法面向网页聊天，不会使用大模型进行摘要，并且需要 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 编码 Agent 的贡献者指南 · CONTRIBUTING.md · CHANGELOG.md

许可证

MIT

---

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