Claude Code Crashed Mid-Task on an Aggregator Key: Rebuilding the Session Without Replaying the Whole Job

What survives a crash and what doesn't

A Claude Code session is a conversation between your local CLI and a model behind an API. When the process dies or the key stops working (balance exhausted, revoked), the local side usually leaves traces; the remote side does not.

• Survives locally: the session transcript (JSONL or similar log under the Claude Code data directory), files already written to disk, git commits, shell history, and any tool output that was printed or logged.
• Does not survive: the model's in-memory reasoning, the full conversation context held by the API, and any tool calls that were planned but never executed. The next request starts from whatever context you explicitly send.

So recovery is not "reconnect to the same session." It is "reconstruct enough state to continue safely."

Step 1: Find the local session log

Claude Code persists conversation history per project. Locate it before doing anything else.

• Check the Claude Code data directory (commonly under your home directory, e.g. ~/.claude/ or a platform-specific equivalent; verify the path for your version).
• Look for JSONL transcripts keyed by project path and session ID.
• If you launched with a custom config or --resume, note the session ID so you can find the right file.

Read the tail of the transcript to see the last successful tool call and the last assistant message. That is your true recovery point—not the last thing you remember asking.

Step 2: Reconcile the workspace against the transcript

The transcript records what the model said it did; the filesystem records what actually happened. Compare them.

• Run git status and git diff to see uncommitted changes.
• Check whether files mentioned in recent tool calls exist and match expected content.
• Identify any partially written files (truncated edits, half-applied patches).
• If you have commits, git log --oneline -n 20 shows the last known-good checkpoint.

A crash mid-edit can leave a file syntactically broken. Decide whether to keep, revert, or manually finish that one file before resuming.

Step 3: Write a compact handoff summary

This is the key step for minimizing USDC burn. Instead of re-sending the entire transcript, extract a short state document:

• Goal: one or two sentences on the overall task.
• Done: bullet list of completed work, with file paths and commit hashes.
• In progress: the exact file and change that was interrupted.
• Remaining: ordered list of next steps.
• Constraints: conventions, commands, and gotchas the model must respect.
• Known failures: approaches already tried that did not work, so the model does not repeat them.

Keep it under a page. This summary replaces thousands of tokens of history with the few hundred that actually matter for the next decision.

Step 4: Restart Claude Code with an explicit resume prompt

Start a fresh session and lead with the handoff, not the original request.

• Paste the summary as the first message.
• State clearly: "We are resuming an interrupted task. Do not redo completed items. Start from 'In progress' and verify current file state before editing."
• Ask the model to read the specific files it needs rather than dumping them into the prompt; tool reads are cheaper and more accurate than pasted context.
• If the task is large, resume in phases: finish the interrupted file, run tests, then continue the remaining list.

A fresh session with a tight handoff often costs far less than a resumed full transcript, because you are not paying to re-process history on every turn. On an aggregator where you pay official price × 1.3, that difference compounds across many turns.

Step 5: Prevent the same crash next time

• Checkpoint after every meaningful unit of work: commit, or at least note the file state, so the recovery point is clean.
• Keep the handoff fresh: update a short PROGRESS.md as you go. If the session dies, that file is your resume prompt.
• Watch key balance: aggregator keys fail when USDC runs out. Top up before long runs, and prefer smaller scoped sessions over one massive one.
• Use plan mode for big jobs: have the model produce a plan and write it to disk before executing, so the plan survives a crash even if the conversation does not.
• Avoid giant pasted contexts: they increase per-turn cost and make transcripts harder to summarize after a failure.

Why this matters on an aggregator key

The recovery workflow above is provider-agnostic, but it pays off more on an aggregator because of the pricing model. You pay official price × 1.3 per call. Replaying a long transcript to "catch up" means paying that multiplier on tokens you already paid for once. A compact handoff, targeted file reads, and phase-by-phase resumption keep the re-sent context small.

If you also contribute keys, remember the other side of the ledger: contributors are credited official price × 1.1 (or × 1.2 for premium) in USDC. That does not change recovery strategy, but it is worth knowing when you decide whether to top up or contribute.

A short recovery checklist

• Locate the session transcript and find the last successful tool call.
• Reconcile git status and file contents against the transcript.
• Write a one-page handoff: goal, done, in progress, remaining, constraints, failures.
• Start a fresh session, paste the handoff, forbid redoing completed work.
• Resume in small phases; verify with tests before continuing.
• Commit and update the progress file after each phase.