compact-handoff

compact-handoff makes the /handoff skill do the job of /compact. /compact-handoff runs the skill, checks that the handoff file really landed on disk, replaces the whole conversation with a short pointer to that file and sends the continue prompt, so the work goes on in the same terminal with a clean context. It is for long sessions where the built-in summary loses too much and opening a new window to paste a resume prompt breaks the flow.

The handoff comes from two skills in the same repo. A handoff is a Markdown file under plans/handoffs/ with the goal, the current state, every approach tried and why it was kept or dropped, the decisions taken and rejected, measured numbers, your corrections and preferences, and ordered next steps. Each new file inherits the chain tag of the previous one and adds one to its sequence number, so each stretch of a long task can see the ones before it.

handoff-compact tackles a similar problem the other way round: it rewrites every compaction, automatic ones included, as a handoff message written by a fork of the session. compact-handoff runs only when you call it, keeps the handoff as files in your repo and leaves every other compaction alone.

What it does

• /compact-handoff [note] runs /handoff, then continues from the handoff’s “Where We’re Going” section. The note goes to the skill.
• /compact-handoffplan [note] runs /handoffplan, which also writes a phased plan and tracked tasks (beads by default), then starts executing Phase 1.
• Nothing changes unless the handoff checks out. If a file is missing or holds fewer than 200 characters, the turn was interrupted, or the skill reports a failure, the context stays as it was and a toast says why.
• /compact-handoff cancel drops a run that got stuck. Only one run goes at a time.
• When the context passes 70%, a toast suggests /compact-handoff, once until the next swap.

Install

Needs Claude Code 2.1.287 or later, plus the repo’s handoff and handoffplan skills, version 2.1.0 or later. The author tested the mod on Claude Code 2.1.300 and labels it experimental.

git clone https://github.com/REMvisual/claude-handoff.git
cp -r claude-handoff/skills/handoff ~/.claude/skills/
cp -r claude-handoff/skills/handoffplan ~/.claude/skills/
claude plugin marketplace add REMvisual/claude-handoff
claude plugin install compact-handoff@claude-handoff

The last command also installs compact-handoff-answer, which compact-handoff’s plugin.json declares as a dependency. If /plugin does not list it, add it with claude plugin install compact-handoff-answer@claude-handoff. Then run /compact-handoff when the context gets heavy. To remove both, run claude plugin uninstall compact-handoff@claude-handoff and then claude plugin prune, which drops the companion.

How it works

The mod chains its steps because the engine refuses some of them at certain moments:

1. A command hook cannot start a prompt, so a short timer launches the skill with a compact-mode argument. In that mode the skill asks no questions, commits the session’s work and writes the handoff (and the plan).
2. During that turn, the mod looks at the file path of each Write and Edit call in the main session, not in subagents, and records the ones named like a handoff or plan file. It does not change or block any call.
3. When the turn ends, it reads those files back from disk. If they pass, it queues a hidden internal command, because compaction is refused while a turn runs.
4. That command asks the engine to compact, retrying every half second up to 40 times while it is refused. A plugin cannot answer a compaction it started itself, so the companion, about 20 lines long, answers only compactions whose instructions begin with compact-handoff:v1 and swaps the conversation for one message naming the files. No summarizer runs, so this step takes milliseconds.
5. The mod then submits the skill’s own paste prompt as if you had typed it, and the new context starts by reading the handoff.

What it costs: the handoff turn is an ordinary skill turn over the whole conversation and uses your plan like any other turn. The swap adds no model call, and the continue prompt opens a new turn on a small context. Without the companion, the engine summarizes as usual with the mod’s note as instructions, and a toast tells you. The mod makes no network calls. It keeps only the state of the current run and whether the 70% toast has been shown; the handoffs stay in your repo.

Limitations

• Version 0.1.1, marked experimental and tested by the author only on Claude Code 2.1.300. The events and methods it relies on can change between Claude Code versions.
• Where an organization manages Claude Code, compaction hooks from user-installed plugins do not run, so compact-handoff-answer cannot answer the compaction.
• Your own Stop and SessionStart hooks still run around the swap, and slow ones lengthen it.
• Classic PreCompact hooks, including the optional one in the same repo, do not fire on these compactions. SessionStart hooks with the compact matcher still do.
• The author documents it only in the terminal.