claude-code-handoff

claude-code-handoff

Parse the local Claude Code session jsonl structure, diagnose the cause of interruption, automatically restore context or a handoff document, and guide the continuation of the task.

Use Cases

1. Task handoff: Development work was started with Claude Code CLI and is halfway done, and now needs to be taken over by Gemini (Antigravity platform).
2. Deadlock/limit interruption recovery: Claude Code encountered errors during operation such as API rate limit exceeded (429 Rate Limit) or context window exceeded (422 Context Window Exceeded), causing a forced stop, and the work needs to be seamlessly migrated to Gemini to continue.
3. Status diagnosis: Quickly view the latest local Claude Code session, inspect the last executed conversation history, the tools called, and the runtime git branch and cwd information.

How It Works

1. Locate the Session file: Based on the passed-in session ID(such as a UUID) or session 文件名, automatically search the Claude directories (including the official ~/.claude/projects/) for the corresponding .jsonl file. Passing in a specific local file path is also supported.
2. Extract history and status：
   • Extract the conversation history of the most recent few turns from the session;
   • From attachment events, extract the last generated HANDOFF.md ；
   • Analyze the most recent system and assistant events to see whether there are any errors.
3. Output Handoff and write it to disk：
   • Automatically generate/update in the project root directory HANDOFF.md. If the session contains a loaded HANDOFF.md attachment, use it as the source of truth; otherwise synthesize a draft version based on the recent context.
   • Generate a piece of instruction for the user to directly copy and paste to the continuing Agent to guide the follow-up work.

Usage Steps

1. The user invokes this skill in the conversation, passing in a specific session ID or jsonl file path.
2. The Agent executes the parsing script:

   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]
   

3. According to the prompt in the output, copy the handoff instruction and load the updated HANDOFF.md to continue working.