auto-handoff

auto-handoff writes a handoff document when you leave a Claude Code session idle for 50 minutes, while the 1-hour prompt cache is still warm. The document records where the work stands, so a fresh session can pick it up instead of paying full price to reread the old conversation once the cache has expired.

Install

Needs Claude Code 2.1.287 or later.

claude plugin marketplace add obie/auto-handoff
claude plugin install auto-handoff@auto-handoff

The plugin loads at the next session start, and there is nothing to run. When the 50 minutes are up, a toast says it is running /auto-handoff:handoff, the skill that ships with it. You can also run that skill by hand.

The plugin name is the same as that of Alex Hillman’s auto-handoff, a different mod that clears a long session at 160k tokens and seeds a fresh one with a brief. If you load both, check which one you are configuring or turning off.

There are two settings, in /plugin configure auto-handoff or through claude plugin configure auto-handoff@auto-handoff --values-stdin with a JSON object on stdin:

• minutes (50): idle time before the command runs.
• command (auto-handoff:handoff): the slash command to run, written as you would type it, arguments included. A command of your own runs with nobody there to approve anything, so give it allowed-tools for what it calls, or use a permission mode that lets it write.

How it works

The idle clock starts when a turn of the main conversation ends. Subagent turns leave it alone, and any new turn stops it. When it reaches minutes, the module runs the command through command.run, as if you had typed it. After that it stays quiet until you send a prompt or run a command yourself; a background task reporting in or a scheduled trigger does not rearm it. /clear cancels a pending handoff.

From prompt.submit and command.run it reads only whether the prompt or command came from a person, never its text. The module keeps two values in plugin state, when the idle period began and whether it has already handed off, and writes nothing to disk itself.

The bundled skill writes docs/handoffs/<timestamp>-<slug>.md in your project, covering the goal, status, decisions, dead ends, files, verification commands, next steps and open questions. It runs date and git status to do it and commits nothing. Since nobody is there to answer a permission prompt, the skill pre-approves those tools in its allowed-tools and finishes in the default permission mode.

The handoff is an ordinary model turn that counts against your usage: each model request in it costs one cached read of the whole conversation, plus the output of writing the document. It also keeps the cache warm for another hour, so the original session is still cheap to resume if you come back within it. The module makes no network requests of its own.

idle-compact uses the same 50-minute idea to compact the session instead: you carry on in the same session from a summary, where auto-handoff leaves the conversation intact and puts its state in a file.

Limitations

• It assumes the 1-hour cache. A session that has dropped to the 5-minute cache, which the README says happens in usage overage, needs a much smaller minutes. The plugin cannot tell which cache a session has.
• Late timers skip. If the machine slept and the timer fires more than 10% late (after 55 minutes with the default), a toast says the cache is already cold and nothing runs.
• The timer lives in the Claude Code process. Quit Claude Code and no handoff happens.
• Unapproved tools stall it. If the model reaches for a tool the command has not pre-approved, the turn waits at the permission prompt until you return.