What to do when you hit the Claude Code usage limit mid-task

Hitting a 5-hour session cap or weekly usage limit in Claude Code (or Codex) usually happens three-quarters of the way through a debugging session: four files are half-edited in your working tree, two dead ends have already been ruled out, and the agent stops responding before it can write a summary.

Why you can still extract the session after the limit hits

When Claude Code blocks further turns with a usage limit message, you cannot ask it to "summarize our progress for another agent" because that request itself consumes tokens. However, Claude Code has already flushed every turn, tool call, shell output, and file edit to ~/.claude/projects/<project>/<session>.jsonl on your disk.

Because the transcript is local, a local binary can read it without calling the API and assemble a structured handoff packet for whichever agent you still have quota on (Codex, Gemini CLI, Cursor, opencode, Aider, or Qwen Code).

One-command continuation with `deja handoff`

In the same project directory, run:

# Install once (indexes existing ~/.claude, ~/.codex, ~/.cursor history on disk)
brew install deja-vu

# Package the latest session in this repo and launch Codex directly with it
deja handoff --to codex --exec

deja handoff reads the most recent session in the current working directory, compresses it into a bounded (~6 KB), secret-redacted briefing, and passes it as the initial prompt to the target agent. Supported --to targets include:

deja handoff --to codex --exec
deja handoff --to gemini --exec
deja handoff --to opencode --exec
deja handoff --to cursor --exec
deja handoff --to qwen --exec
deja handoff --to aider --exec

If you prefer to inspect the briefing first or paste it into a browser or IDE chat window, omit --exec:

deja handoff --to codex | pbcopy

What goes into the handoff packet

Dumping a raw 400 KB JSONL transcript into a new agent wastes its context window and buries the current state under old tool output. Instead, deja handoff extracts five specific sections from the local session and repository state:

The original goal and latest user request — what you asked for at the start and what the last instruction was before the cap hit.
Files modified and read — which paths were edited vs inspected.
Commands run and their outcomes — which test suites or build commands passed or failed, including the last failing error lines.
Settled decisions and rejected paths — approaches the previous session already tried and backed out of, so the new agent does not repeat the same dead end.
Uncommitted working-tree state — how the current git status relates to where the previous agent stopped.

Interactive handoff from the TUI

If you had several parallel terminals open and want to pick a specific session rather than the most recent one, run deja with no arguments to open the terminal UI, highlight the session, and press o to open a handoff menu for any installed agent on your machine.

Letting the new agent query older sessions via MCP

A handoff packet covers the session that just stopped. If you also want the backup agent to search earlier sessions in the repo on demand (via the deja MCP tool), register deja once across every agent installed on your machine:

deja install

Then when Codex or Gemini CLI takes over, it can call deja with mode: "handoff" or mode: "recall" directly without leaving its own session.