Claude Code Handoff

claude-code-handoff

解析本地 Claude Code 的 session jsonl 结构，诊断中断原因，自动恢复上下文或交接文档并指导接续任务。

适用场景

• 任务接力：开发工作由 Claude Code CLI 启动并开发至一半，现在需要由 Gemini (Antigravity 平台) 接管。
• 死锁/限制中断恢复：Claude Code 在运行过程中遇到了 API 频率超限 (429 Rate Limit) 或上下文超长窗口超限 (422 Context Window Exceeded) 等错误强制中止，需要无缝迁移至 Gemini 续作。
• 状态诊断：快速查看本地最新的 Claude Code session，查看最后执行的对话历史、调用的工具以及运行时的 git 分支和 cwd 信息。

工作原理

• 定位 Session 文件：

根据传入的 session ID（如 UUID）或 session 文件名，在 Claude 目录（包括官方的 ~/.claude/projects/）中自动搜索对应的 .jsonl 文件。同时也支持传入具体的本地文件路径。

• 提取历史与状态：
• 提取 session 中最近几轮的对话历史；
• 从 attachment 事件中提取最后生成的 HANDOFF.md ；
• 分析最近的 system 和 assistant 事件是否有报错。
• 输出 Handoff 并落盘：
• 自动在项目根目录生成/更新 HANDOFF.md。如果 session 包含已加载的 HANDOFF.md 附件，则以它为准；否则根据最近的上下文合成一份草拟版本。
• 生成一段指令用于用户直接复制粘贴给接续的 Agent 引导后续工作。

使用步骤

• 用户在对话中调用此技能，传入特定的 session ID 或 jsonl 文件路径。
• Agent 执行解析脚本：

   python3 {path_to_public-agent-skills}/skills/claude-code-handoff/scripts/claude_handoff_parser.py -f <session_id_or_file_path> [-o /path/to/HANDOFF.md]

• 根据输出中的提示复制接力指令，并加载更新后的 HANDOFF.md 继续工作。