cafe3310 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继续工作。