ctx-handoff

ctx-handoff moves a long Claude Code session into a fresh conversation without you typing a command. When the main conversation’s context passes a threshold, it has the model write a handoff, runs /clear itself and submits the handoff as the first message of the new conversation. While you are away it keeps the prompt cache warm, then saves a handoff instead of clearing.

The author built it for long sessions on a 1M-context model with a Claude subscription, where the prompt cache lasts an hour, and marks it experimental.

What it does

• Handoff at a threshold. When a turn ends with an answer and the context is at 600k tokens or 80% of the window, whichever is lower, it hands off. On a 200k window that means 160k.
• Waits for background work. If background Bash shells, workflows, Monitor tasks or subagents are still running, it shows a status line and checks again on the turn their completion notice starts.
• A short brief for the new conversation. The handoff opens with a HANDOFF: goal line, then the current state, decisions and their reasons, relevant files and commands, next steps and open questions for you. The new conversation is told to sum up what it understood and wait for you instead of acting.
• Idle refresh. After 55 idle minutes it sends a tiny forked request to refresh the prompt cache, up to three times, about four hours in all. At the fourth point it saves an “away handoff” and leaves the conversation as it is.
• Coming back. With an away handoff pending, your first message is held. /handoff-resume clears and starts the new conversation with the handoff plus your message. /handoff-continue, or sending the message again, drops the handoff and continues in the old conversation. Slash commands pass through.
• Main conversation only. Subagent turns are ignored, and a context under 30k tokens skips both the refresh and the away handoff.

Two more commands: /handoff-status prints the context in use, the threshold, the refresh state and any pending away handoff, and /handoff-now yes hands off immediately (without yes it only warns that the conversation will be cleared).

Install

Needs Claude Code 2.1.287 or later and git. The repository has no marketplace, so you clone it and load the folder with --plugin-dir:

git clone https://github.com/cablate/ctx-handoff-mod ~/.claude/mods/ctx-handoff
claude --plugin-dir ~/.claude/mods/ctx-handoff

Run /handoff-status to check that it loaded. To load it in every session, put the folder’s absolute path in CLAUDE_CODE_PLUGIN_DIRS under env in ~/.claude/settings.json, separating several folders with ; on Windows and : on macOS and Linux:

"env": { "CLAUDE_CODE_PLUGIN_DIRS": "/home/you/.claude/mods/ctx-handoff" }

How it works

The mod acts on your behalf: it runs /clear through command.run and sends prompts through prompt.submit. It does so at the threshold and after /handoff-resume, /handoff-continue and /handoff-now yes, never at any other time.

• What it reads. turn.complete reads the session’s context usage after each main-conversation answer and restarts the idle timer. prompt.submit sees the prompts you type, to stop the idle timer and to hold the first one when an away handoff is pending; it also reads task notifications to drop finished background tasks. tool.call reads the results of Bash, Workflow and Monitor calls to note background task IDs, and drops an ID on TaskStop. Those IDs live in memory only.
• What it spends. Each handoff is a model.fork: a side request over the whole conversation that returns the handoff text. Each idle refresh is another fork over the full context that answers one word. The author measured a fork over a 102k-token conversation reading about 99.5% of its input from cache, but does not state what a handoff or a refresh costs in tokens or usage.
• What it saves. The mod’s store keeps the last five handoffs (time, session id, kind, token count and text), the refresh setting, and a pending away handoff with any held message.
• Network. It makes no calls of its own. The forks are model requests sent by Claude Code like any turn.

The values are constants at the top of hooks/register.ts: THRESHOLD (600,000), WINDOW_RATIO (0.8), IDLE_MS (55 minutes), MAX_REFRESH (3) and MIN_TOKENS (30,000). Edit them there; changes hot-reload if the folder is watched. The author chose 600k to hand off less often and suggests lowering it if the model gets worse before the handoff fires. /handoff-refresh off stops the idle refresh, and the away handoff is then saved after 55 idle minutes. There is no switch for the automatic handoff: raise THRESHOLD or turn the mod off.

cache-tax also keeps the cache warm with pings, without a handoff; cache-keeper pairs keep-warm pings with a /handoff you start yourself, and asks before a costly cold send.

Limitations

• Refresh assumes a 1-hour cache. API key, Bedrock and Vertex users, and subscribers drawing on usage credits, get a 5-minute cache, so each refresh at 55 minutes rewrites the whole context. Run /handoff-refresh off. The mod does not detect which cache you have.
• Not proven end to end. It is not confirmed that a fork’s cache read extends the main conversation’s cache, and no real session has yet been seen reaching 600k. The author’s nine claude plugin test cases pass, covering the threshold, a 200k window, refresh, resume and the deferrals.
• Background detection is partial. Workflow and Monitor IDs are parsed from output text in an unverified format. A task that never ends, such as a dev server, holds the handoff until its record expires after 12 hours; /handoff-now yes forces it.
• A held message keeps only its text; images are dropped.
• A hot reload resets the timers and the background tracking.
• Its messages, and the prompts it sends the model, are in Traditional Chinese.
• The author marks it experimental: a Claude Code update may require changes.