Auto Handoff

auto-handoff

A Claude Code plugin that writes a handoff document when you walk away from a session.

Claude Code keeps a session's context in a prompt cache that expires an hour after the last request. A turn sent inside that hour reads the conversation back at a fraction of the usual input price. Once the hour is up, the next turn pays full price to read everything again, and on a long session that is slow and expensive.

auto-handoff watches the gap. When a session has sat idle for 50 minutes it runs a handoff command while the cache is still warm, so the state of your work lands in a file that a fresh session can resume from.

Install

The plugin loads at the next session start.

It is built on the function hooks plugin API, which is early access and may change between Claude Code releases. Development and testing happened on Claude Code 2.1.289.

How it behaves

- The idle clock starts when a turn of the main conversation ends. Any new turn restarts it, whoever started that turn. A subagent finishing leaves it alone.
- After minutes of idle time the plugin runs command as if you had typed it, and a toast says so.
- You get one handoff per absence. The plugin then stays quiet until you send a prompt or run a command yourself. A background task reporting in, or a scheduled trigger firing, keeps it quiet.
- /clear cancels a pending handoff.
- A laptop that slept through the wait wakes with a cold cache. The plugin sees that its timer fired late and skips the handoff, since running it then would cost the full price it exists to avoid.

The bundled skill

The default command is /auto-handoff:handoff, a skill that ships with the plugin. You can run it by hand too.

It writes docs/handoffs/-.md, covering the goal, status, decisions, dead ends, files, verification…