handoff-compact

handoff-compact replaces the summary Claude Code writes when it compacts a session. A fork of the session writes a handoff along a fixed outline instead: the goal, what is done and what proves it, the next step, the decisions and their reasons, and the approaches already ruled out. That one message replaces the conversation, and the work goes on from it. It is meant for long, unattended runs that compact several times and must not lose the thread.

The author’s case against the built-in summary: it keeps what a summarizer finds important and drops what the next stretch of work needs, such as why a decision was made or which paths already failed. Version 0.2 was piloted on a live session through six automatic compactions in one long turn.

What it does

• Every compaction becomes a handoff. The automatic ones at Claude Code’s compact window and the ones you start with /compact. Text after /compact reaches the fork as what to stress. Subagents still compact the usual way.
• A nine-part outline. Goal, state and proof, in progress, next step, decisions and reasons, ruled out, blocked or open questions, files and commits, and the command that verifies the state. Every section must appear, with “nothing” when it is empty. The fork is told to prefer exact paths, commands, commit hashes and numbers, to let your latest message override the plan, and to write in the conversation’s language. A text file of your own, one section per line, replaces the outline.
• A tail that does not depend on memory. Your last 10 prompts are appended word for word, up to 1,000 characters each, and the last 10 answers shortened to 600 characters. A later compaction carries an earlier handoff’s tail forward, so your own words survive any number of compactions.
• A file copy. Each handoff is also saved as Markdown, and the message in the conversation gives its path.
• Claude Code’s summary, once. /compact classic compacts this one time without the mod. Words after classic go to Claude Code as usual.
• A fallback. If the fork fails, on a cold cache or an API error, Claude Code compacts with its own summarizer, told to follow the outline but without the verbatim tail. If the module throws, Claude Code skips it and compacts as usual.

auto-handoff and ctx-handoff take the other route: at a threshold of their own they write a brief, run /clear and start a fresh conversation from it. handoff-compact keeps Claude Code’s compaction and its timing, and only replaces what it writes, /compact included.

Install

Needs Claude Code 2.1.287 or later. The repository is its own marketplace:

claude plugin marketplace add trytofly94/handoff-compact
claude plugin install handoff-compact@handoff-compact

There is nothing to run: the next compaction is a handoff. To get there sooner, run /compact, or lower Claude Code’s compact window with CLAUDE_CODE_AUTO_COMPACT_WINDOW or autoCompactWindow in your settings.

The options live in /plugin (configure), in /config or under pluginConfigs in your settings:

• trigger (core): who decides when to compact. With core, Claude Code does, and each compaction costs one model call, the fork. With self, the mod does; see Limitations before choosing it.
• keepVerbatim (10): the size of the tail, 0 to 30.
• handoffDir, outlineFile and adapter: where the files go, your own outline, and an optional executable described below.
• precompute (skip): turns off Claude Code’s background pre-compaction, whose summary the mod would throw away; core leaves it on.
• threshold (70), window (0, automatic) and autoContinue (never): only for trigger: self.

How it works

• Events. By default the mod hooks one event, session.compact, and answers it in place of Claude Code’s summarizer, returning the handoff as the single message that replaces the conversation. session.measure and turn.complete are hooked only with trigger: self, to note the threshold after each response and to compact once the main turn ends with an answer, not after a subagent’s turn, an interrupt or an error.
• The fork and what it spends. The handoff comes from model.fork, a side request over the conversation that reads it from the prompt cache and has no tools, so the main context is not touched. The code passes the outline prompt and no model of its own. The author puts the cost at mostly cache reads plus the handoff’s own output, about what the summary Claude Code would otherwise write costs.
• What it reads. The conversation’s messages, without system reminders, for the tail. With trigger: self it also reads CLAUDE_CODE_AUTO_COMPACT_WINDOW and autoCompactWindow in ~/.claude/settings.json to find the window, unless the window option or the adapter sets it.
• What it saves. Each handoff goes to ~/.claude/handoffs/<session-id>-<timestamp>.md, or your handoffDir, with the folder created by mkdir -p. The file holds the fork’s text, any state files the adapter lists and the tail. If the write fails, the handoff still reaches the conversation, without a path. Nothing in the module deletes old handoffs.
• Acting on your behalf. Only with trigger: self: after Claude Code’s summary, the mod sends the handoff as a prompt through prompt.submit and shows a toast with the file’s path. With autoContinue: never that prompt asks the model only to reply “Handoff read.” and wait. With always, or with adapter when the adapter says so, it tells it to read the listed state files and carry on with the next step. In the default mode Claude Code’s own compaction continues the turn anyway.
• Network. The mod makes no calls of its own. The fork is a model request Claude Code sends like any other.
• The adapter. An executable you write for what only your setup knows, such as which files hold the project’s state or whether a session runs unattended. It gets JSON on stdin (phase, session id, working directory, context size) and can answer with window, threshold, autoContinue, notes and stateFiles. It runs after each response in self mode, cached for five minutes, and while a handoff is written. Any failure, a 10-second timeout included, counts as no answer.

Limitations

• With trigger: self, Claude Code does not run a plugin’s own session.compact hook for a compaction that plugin started. It writes its usual summary, and the handoff follows as the next prompt: two summaries in the context, at the cost of two. The author advises self only where you cannot set Claude Code’s window.
• In self mode a compaction waits for a turn to end. If a new turn starts while the fork is writing, the attempt is dropped and retried at the end of a later turn, two minutes on at the earliest; if Claude Code refuses the compaction, the mod waits ten minutes.
• The author lists the CLI and the Code tab of Claude Desktop. The mod draws nothing apart from the self mode’s toast. Mod events and methods can change between Claude Code versions.