obie / 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
 [code] 
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 commands, next steps and open questions. To do that it runs `date` and `git status`, then writes that one file. Nothing gets committed.
Nobody is there to answer a permission prompt when it runs, so the skill pre-approves those tools for itself through `allowed-tools`. It completes in the default permission mode.
## Configuration
| Option | Default | Meaning |
| --- | --- | --- |
| `minutes` | `50` | Idle time before the command runs |
| `command` | `auto-handoff:handoff` | Slash command to run, without the slash |
Set them with `/plugin configure auto-handoff` inside Claude Code, or from a shell:
 [code] 
A command of your own has to get through an unattended run. Give it `allowed-tools` for whatever it calls, or run your sessions in a permission mode that lets it write.
## Limits
- The default of 50 assumes the one-hour cache. A session that has dropped to the five-minute cache, as happens in usage overage, needs a much smaller `minutes`. The plugin cannot tell which cache a session has.
- The handoff is a turn like any other. Each model request in it costs one cached read of the conversation, and the turn keeps the cache warm for another hour.
- The timer lives in t