VIP Evacuation: Rate-Limit Rescue

You're deep in a task and Claude Code stops: usage limit reached. Re-explaining everything in a fresh session costs time and tokens. Bouncer builds the handover for you.

When it triggers

• Automatically: the Stop hook checks the end of the session transcript for rate-limit signatures (rate_limit_error, "usage limit reached", "5-hour limit", HTTP 429). If it finds one, the rescue is built and Claude Code shows:

  🚨 BOUNCER RESCUE: rate limit hit. A full handover (goal, interrupted task, git state)
  was copied to your clipboard. Paste it into a fresh session or another tool to keep going.

• Manually, at any time:

  bouncer rescue            # uses the latest transcript for the current folder
  bouncer rescue --print    # also print it to the terminal
  bouncer rescue --transcript ~/.claude/projects/<project>/<session>.jsonl

The package is copied to your clipboard and saved to ~/.bouncer/last-rescue.md.

What's inside: ground truth first

Every rescue package contains facts only. Nothing in these sections is generated by AI:

Section	Source
📍 Workspace	exact cwd and git branch
🎯 Initial goal	your first prompt, verbatim
⏸️ Interrupted task	your last prompt, verbatim
📝 Files modified this session	Edit / Write / MultiEdit tool calls in the transcript
🧾 git status --short	verbatim
📊 git diff --stat	verbatim
💬 Full prompt history	every prompt, verbatim (long histories keep the first and last 10)
▶️ Instructions	tell the next agent to check git diff before redoing anything

🥇 Gold bonus: Executive Progress Summary

On Level 3, Bouncer adds three AI-written bullets: what was done, the current state, and the next step. They sit in a separate, clearly labelled section below the facts, so a weak summary can never hide or replace a verbatim detail. If the AI call fails, the section is simply left out.

Crowd control: the /clear handover

Long sessions get expensive because every turn re-reads the whole context. When the real context size of your session goes over 75% of its context window (150k of 200k, or 750k of a 1M window), Bouncer acts. In balanced mode it shows one warning and lets you pick the moment (bouncer rescue, then /clear). In strict mode it blocks the next prompt and builds a lighter handover, including the prompt you just tried to send:

🕶️ BOUNCER  ·  🧹 CONTEXT FULL
──────────────────────────────────────────────
This session's context is ~186k tokens, and every turn re-reads all of it.
✔ Your handover (goal, recent prompts, git state and this prompt) is on your clipboard.

   👉  OPEN A NEW SESSION ( /clear )   →   PRESS CTRL + V   →   DONE !

Want to stay in this session? Re-send your prompt ending with " !".

The token count comes from the usage that Claude Code records for each reply. It is not the transcript file size, which overstates context by 2–3x because of tool output and metadata. For older transcripts without usage, Bouncer falls back to a 130 KB file-size limit.

Change the limit in ~/.bouncer/config.json:

{ "contextBloatThresholdTokens": 200000 }

Continuing in another tool

The handover is plain Markdown, so you can paste it into Claude Code on another account, Codex, Cursor or any chat. The next agent gets the same goal, the same unfinished task and the real repository state.