claude-code-session-repair

claude-code-session-repair

Recover a Claude Code session that returns HTTP 400 on every request — typing, /compact, and claude --resume all fail — because its transcript JSONL contains a malformed content block.

When a Claude Code session's transcript gets into a state the Anthropic Messages API rejects, the session is held hostage: every subsequent API call — a new prompt, /compact, even claude --resume <id> — returns the same 400 and exits. Most people give up and abandon the conversation. These skills diagnose the exact corruption and surgically repair the JSONL so the session opens normally again, losing nothing but the one malformed block.

What it catches

Two distinct corruptions, both producing an unrecoverable-looking 400, each with its own diagnosis and fix:

Both are upstream Claude Code serialization bugs (see the 150+ report meta-tracker). Until they're fixed, this is your recovery path — and even after a fix, sessions corrupted before you upgrade still need repair.

Quick start

You:    Resume keeps failing — "API Error: 400 ... unexpected tool_use_id
        found in advisor_tool_result blocks: srvtoolu_01Ts..."
Claude: [invokes claude-code-session-jsonl-orphan-advisor-tool-result]
        Found the orphan pair — server_tool_use at L89 and its
        advisor_tool_result at L94 share one message.id but the client
        reconstructed them as two messages. Backing up, deleting both
        halves, verifying... orphan blocks now 0. Resume from <cwd>:
        claude --resume <id>

Installation

Claude Code (plugin — recommended):

/plugin marketplace add wan-huiyan/claude-code-session-repair
/plugin install claude-code-session-repair@wan-huiyan-claude-code-session-repair

Git clone (always works):

git clone https://github.com/wan-huiyan/claude-code-session-repair.git \
  ~/.claude/skills/claude-code-session-repair-src
# then symlink or copy the two skill dirs under plugins/.../skills/ into ~/.claude/skills/

Note: a corrupted session can't load these skills itself (it 400s before it can do anything). Install them, then run a fresh Claude Code session and point it at the broken one — or follow the SKILL.md steps by hand.

How it works

Both skills follow the same shape:

1. Locate the file — ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl. The encoding collapses both / and _ to - (lossy), so worktree paths need git worktree list to resolve — the skills cover this gotcha.
2. Diagnose precisely — find the offending block by the id in the 400 (orphan) or by JSON-walking content arrays (whitespace). Plain grep is explicitly not enough for the whitespace case.
3. Back up, then surgically edit — delete or patch only the malformed block(s). The orphan fix deletes both halves (deleting one just promotes the other to the new orphan).
4. Verify — confirm zero offending blocks remain and every line is still valid JSON, then re-resume.

Key design decisions