auto-handoff writes a Claude Code handoff doc before the cache goes cold

A Claude Code session that sits idle for an hour pays full input price on the next turn, because the one-hour prompt cache has gone cold and the whole conversation has to be read again. auto-handoff, released by Obie Fernandez on 4 October, is a plugin that catches the gap. It runs a handoff command at 50 minutes of idle time, while the cache is still warm, so the state of the session lands in a Markdown file that a fresh conversation can resume from.

What it does

The idle clock starts when a turn of the main conversation ends. A new turn restarts it, whoever started it, and a subagent finishing is ignored. After 50 minutes, the plugin runs the configured command as if the user had typed it, a toast says so, and one handoff goes out per absence.

Two cases the README calls out: /clear cancels a pending handoff, and a laptop that slept through the wait wakes with a cold cache and the plugin skips the handoff then, because running the command at full price would waste exactly what the plugin exists to save.

The bundled skill

The default command is /auto-handoff:handoff, a skill that ships with the plugin. It runs date and git status, then writes one file at docs/handoffs/<timestamp>-<slug>.md. The file covers the goal, status, decisions, dead ends, files, verification commands, next steps and open questions. Nothing is committed.

Because nobody is at the keyboard, the skill pre-approves the tools it uses through allowed-tools and runs in the default permission mode. A different command may be set with /plugin configure auto-handoff, but a custom command has to arrange its own approvals or the turn stops at a permission prompt.

Traction and the limits the author names

GitHub shows 92 stars and three forks on the repository, three days after it was created on 4 October. The project is MIT, and development happened on Claude Code 2.1.289.

The README is direct about what the plugin cannot do. The 50-minute default assumes the one-hour cache, so a session that has fallen to the five-minute cache during a usage overage needs a much smaller value, and the plugin cannot tell which cache a session has. The handoff is a turn like any other, so it costs one cached read of the conversation and keeps the cache warm for another hour. The timer lives in the Claude Code process, so it stops when the user quits Claude Code. The plugin is built on the function hooks plugin API, which the README notes is early access and may change between Claude Code releases.

The pattern it fits

An hour-long cache window on a long conversation is now a real cost line in a team's Claude Code bill, and the plugin is the first one that pays attention to the clock instead of asking the user to notice it. The handoff file is also a decent record for a coding agent that has to pick up tomorrow from where the model stopped today.

Source

obie/auto-handoff, GitHub.