How it works
The handover
What it holds
Claude reads your branch, your changes and your last few commits.
Claude writes a short note, called a handover: the goal, the next action, where things stand, the decisions made and what already failed.
Where it is kept
Handovers are plain text files on your disk, in ~/.clear-resume. Nothing is sent anywhere unless you turn on sync (to your own private git remote) or web mode (for Claude Code on the web). Keep secrets out of them.
Each loaded handover is also saved as markdown in ~/.clear-resume/ for 30 days.
When it loads
The plugin checks for a waiting handover when a session starts, after /clear and after compaction (when /compact, or Claude Code on its own, shrinks the chat). When nothing is waiting, it prints nothing.
What does not load it
Known limitation: the loop runs on /clear. A session started with --resume or /resume loads nothing.
Which handover loads
- Each handover belongs to the Claude Code window that wrote it. While that window is open, it is the only one that loads the handover after
/clear. - Other windows on the same project list it when they start, and load it only if you ask.
- Once that window closes, a session on the same branch loads it, if it is 7 days old or less.
- If it is the only one waiting from a closed window, it loads on any branch, if it is 7 days old or less.
- A handover older than 7 days is listed, not loaded.
- After compaction, only this window's own handover loads.
- A handover loads in the checkout it was saved in.
These are the common cases.
The loop
- Claude works and the chat grows.
- With the nudge on, past the size you set, the plugin asks Claude to save a handover.
- Claude saves a handover: you type
/clear-resume:handover, or the nudge asks. /clear: you type it, or the plugin runs it when the turn ends, with the relay on.- The fresh session loads the handover, and Claude carries on.
Worked example
The README's example: a handover in a widget-shop repo, saved, loaded after /clear, and the copy it leaves.
/clear-resume:handover Saved handover "Cart totals rounding" (id 31c9af7). After /clear, the next session in ~/code/widget-shop loads it automatically. /clear clear-resume: loaded handover "Cart totals rounding" (saved just now). A copy to read or share: ~/.clear-resume/loaded/ widget-shop-cart-totals-rounding-31c9af7.md
The copy in ~/.clear-resume/ stays for 30 days: reread what a session started from, or @-mention it in another session.
~/
# the copy, as the README's screenshot of it reads # Cart totals rounding Repo: widget-shop. Branch: fix/cart-rounding. Goal: Cart totals must round to the cent the way the payment provider does, so the checkout total and the receipt always match. Next action: Run npm test -- cart and fix src/cart.js:2 so cartTotal rounds once at the end, half-up, to 2 decimal places. Decisions already made: Round once, at the total, never per line: the payment provider does the same.
Compared with /compact, --resume and /clear
| Claude keeps | You lose | Chat size after | |
|---|---|---|---|
| /compact | Its own summary of the chat | What the summary leaves out | Smaller |
| --resume | The whole chat | Nothing | Same as before |
| /clear | Nothing | Everything, including where you were | Empty |
| clear-resume | A short handover it wrote on purpose | The rest of the chat | Just the handover |
Source: the comparison table in the README.
The model
A model, not a measurement. Claude rereads the whole context for every reply: set a task and see how much it rereads with clear-resume and without it.
On a 200k window, the run without clear-resume compacts on its own at (assumed).
Reread over the task: with clear-resume, without it.
clear-resume
without it: Claude Code compacts on its own
| Resets | Peak context | Context reread | |
|---|---|---|---|
| clear-resume | |||
| without it |
Source: site/model.js, a model, not a measurement.
How the model works
- Each reply adds 5000 new tokens to the context: assumed.
- Claude rereads the whole context for every reply, so the reread figure is the context summed over every reply.
- After a clear, the run restarts at the start size plus the handover: about 780 tokens in the handover, an estimate. Measured on the author's own 104 /clears, 20 to 28 Sep 2026, medians.
- Without clear-resume, the run compacts at nine tenths of the window and keeps an 8000-token summary: both assumed.
- On the API, cache reads are billed at a tenth of the input price.
- The model clears at or below the clear-at size. The plugin asks Claude to save once context is past the size you set, and Claude then saves, so in use, peaks pass it.
Start size
21,200
Stock Claude Code starts at 21,200 tokens before your first message.
Claude Code 2.1.289, Opus 5.5, empty CLAUDE_CONFIG_DIR, cwd with no CLAUDE.md, .claude or .mcp.json above it, 0 MCP servers, 27 tools. One headless "say hi" run; cache_creation_input_tokens 21,200 + input_tokens 2, read from the first assistant message, 2026-10-04.
Source: one headless run, measured 2026-10-04.
77k to 99k
The author's sessions start at 77k to 99k (rules, skills, MCP).
Source: the author's own sessions.
Settings
After install, Claude Code says, or asks about, three options that are not set yet. They belong to the nudge and the relay, which are both off by default.
Nudge to save a handover
auto_nudge
Default: off
Turns the nudge on. Past the Nudge at size, the plugin asks Claude once per session to save a handover, and prints a status line saying so.
Source: the README.
Nudge at
Default: 180k tokens
The context size the nudge waits for. Claude Code keeps it between 50000 and 1000000 tokens.
Source: the README (default), the CHANGELOG (range).
relay
Default: off
A number of clears per Claude Code window, or unlimited. After Claude saves a handover, clear-resume runs /clear when the turn ends and submits the prompt that continues from it. Needs Claude Code 2.1.275 or later; an older build ignores it.
Source: the CHANGELOG.
Set them with /plugin configure clear-resume@clear-resume, or in /config: the nudge settings need Claude Code 2.1.269 or later there. In the Claude Code panel in VS Code, set them from a terminal with claude plugin install clear-resume@clear-resume --config.
The environment variables still work: CLEAR_RESUME_AUTO wins whenever it is set, and CLEAR_RESUME_NUDGE_AT wins when it is a positive number.
Source: the CHANGELOG.
Also opt-in: sync (to your own private git remote) and web mode (for Claude Code on the web).
Source: the README.
What's inside
One skill
/clear-resume:handover
Claude writes the handover and saves it with save.mjs, which reads it on stdin.
Three hooks
hooks.json
SessionStart loads the waiting handover at startup, /clear and compaction, then archives it so it loads once. PostToolUse and Stop check the context size for the nudge and the relay.
Any failure exits 0 with no output: a broken plugin must never block a session.
One Claude Code mod
relay.ts
A mod is a function-hooks module that runs inside Claude Code. This one is the relay: after Claude saves a handover, it runs /clear and submits the prompt that continues from it.
The one program it starts is git rev-parse HEAD, for the stall guard. It sends nothing anywhere.
One store
packages/store
One record schema, shared by the plugin and the VS Code extension. Every reader and writer goes through it, so the files on disk are defined in one place.
Sync, when you turn it on, is a git transport on top of it.
An install copies plugin/ and nothing else. It has no package.json, so an install runs no npm.
Source: the source files, the plugin README and How it works.