Skip to content
Back to search

auto-handoff

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin that writes a handoff document before an idle session's prompt cache goes cold

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/obie--auto-handoff/badge.svg)](/listings/obie--auto-handoff)

HTML

<a href="/listings/obie--auto-handoff"><img src="/api/listings/obie--auto-handoff/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "auto-handoff",
  3. "owner": {
  4. "name": "Obie Fernandez"
  5. },
  6. "metadata": {
  7. "description": "A Claude Code plugin that writes a handoff document before an idle session's prompt cache goes cold",
  8. "version": "0.1.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "auto-handoff",
  13. "source": "./",
  14. "description": "Writes a handoff document when a session has sat idle long enough that its prompt cache is about to go cold.",
  15. "version": "0.1.0",
  16. "author": {
  17. "name": "Obie Fernandez"
  18. },
  19. "keywords": ["handoff", "prompt-cache", "idle", "session", "hooks"],
  20. "category": "productivity",
  21. "homepage": "https://github.com/obie/auto-handoff",
  22. "repository": "https://github.com/obie/auto-handoff",
  23. "license": "MIT"
  24. }
  25. ]
  26. }
README.md · README · 83 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # auto-handoff
  2. A Claude Code plugin that writes a handoff document when you walk away from a session.
  3. 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.
  4. 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.
  5. ## Install
  6. ```
  7. /plugin marketplace add obie/auto-handoff
  8. /plugin install auto-handoff@auto-handoff
  9. ```
  10. The plugin loads at the next session start.
  11. 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.
  12. ## How it behaves
  13. - 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.
  14. - After `minutes` of idle time the plugin runs `command` as if you had typed it, and a toast says so.
  15. - 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.
  16. - `/clear` cancels a pending handoff.
  17. - 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.
  18. ## The bundled skill
  19. The default command is `/auto-handoff:handoff`, a skill that ships with the plugin. You can run it by hand too.
  20. It writes `docs/handoffs/<timestamp>-<slug>.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.
  21. 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.
  22. ## Configuration
  23. | Option | Default | Meaning |
  24. | --- | --- | --- |
  25. | `minutes` | `50` | Idle time before the command runs |
  26. | `command` | `auto-handoff:handoff` | Slash command to run, as you would type it, with any arguments after its name |
  27. Set them with `/plugin configure auto-handoff` inside Claude Code, or from a shell:
  28. ```
  29. echo '{"command": "my-plugin:my-handoff"}' | claude plugin configure auto-handoff@auto-handoff --values-stdin
  30. ```
  31. Arguments go after the command's name, as they would at the prompt. A command that behaves differently when nobody is there can be told so: `my-plugin:park idle-triggered`.
  32. 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.
  33. ## Limits
  34. - 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.
  35. - 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.
  36. - The timer lives in the Claude Code process, so it stops when you quit Claude Code.
  37. - A model that reaches for a tool the command has not pre-approved leaves the turn waiting at a permission prompt until you return.
  38. ## Development
  39. ```
  40. git clone https://github.com/obie/auto-handoff ~/projects/auto-handoff
  41. ln -s ~/projects/auto-handoff ~/.claude/skills/auto-handoff
  42. ```
  43. Claude Code loads the linked folder as `auto-handoff@skills-dir` at the next session start and reloads the hooks module when you save a file.
  44. ```
  45. claude plugin validate .
  46. claude plugin test .
  47. ```
  48. The pieces:
  49. - `hooks/register.ts` is the hooks module: an idle timer armed at `turn.complete` and cancelled at `turn.start`.
  50. - `types/index.d.ts` declares the two values the module keeps in `$.state`.
  51. - `skills/handoff/SKILL.md` is the bundled handoff skill.
  52. - `tests/` runs under `claude plugin test` against a mocked clock.
  53. ## License
  54. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.