How to repair a corrupted Claude Code session file

Q: Is my Claude Code session gone forever?

Usually not. Check whether the .jsonl still exists under ~/.claude/projects/. If it does, inspect it before assuming deletion. Only retention deletion truly removes the transcript.

Guide · August 2026 · ~4 min read

Sessions feel "lost" far more often than they are deleted. The transcript lives on disk at ~/.claude/projects/<project-dir>/<session-id>.jsonl, and most failures mean one record in that file is broken — not that the conversation is gone. This guide covers how sessions get corrupted, how to tell corruption apart from deletion, and how to repair the file.

How sessions get corrupted

Unclean exit. Terminal closed mid-run, laptop battery dying, or a crash leaves the last line half-written. A truncated line isn't valid JSON and the resume parser stops there.
Compaction interrupted. If auto-compact dies mid-write you get a summary record that references messages never persisted. See compaction stuck.
Crash between tool call and result. The agent wrote a tool_use but died before its tool_result arrived (or vice versa) — an orphaned pair the API refuses to replay.
Disk full or sync conflict. Dropbox/OneDrive/iCloud syncing .claude/projects/ can interleave writes or restore stale halves of the file.

Corruption vs deletion — check this first

ls -la ~/.claude/projects/YOUR-PROJECT/*.jsonl

If the .jsonl for your session is there and its size looks sane, it's repairable. If it's genuinely gone, that was retention deletion — see cleanupPeriodDays. Deleted means deleted; nothing recovers it after the fact.

The repair

Three record-level defects cause nearly every "corrupted session": a line that isn't valid JSON, an orphaned tool result, and a broken uuid/parentUuid chain. The diagnosis commands are in the --resume troubleshooting guide.

Fixing them by hand in a text editor works for small files, but real sessions are tens of megabytes of long JSON lines with ids repeated across records — one wrong edit makes it worse. SessionPatch opens the file locally, parses every line, pairs every tool call with its result, walks every parent chain, and lists each defect with click-to-jump. It can safely edit message text, tool input JSON, and remove a linked tool call/result pair. Doctor can guide a record with a missing parentUuid to a proposed prior valid record or root; other structural repairs remain diagnostic. The original file is never touched until you replace it yourself.

FAQ

Is my Claude Code session gone forever?

Usually not. Check whether the .jsonl still exists under ~/.claude/projects/. If it does, inspect it before assuming deletion. Only retention deletion truly removes the transcript.

How do I recover a corrupted Claude Code session?

Open a copy, validate JSONL lines, tool-call/result pairing, and parent links, then repair only the confirmed defect. SessionPatch performs the diagnosis locally; Doctor can guide missing-parent repair; unsupported structural repairs still require careful manual editing.

After recovery

Copy the recovered .jsonl somewhere safe before resuming — resume rewrites the file as the conversation continues. And prevent the next one: avoid force-killing terminals mid-run, keep .claude/projects/ out of sync tools, and back up sessions worth keeping.