claude-auto-handoff plugin
A Claude Code plugin that replaces auto-compact: it writes a handoff brief, clears the session and continues from it
- 125 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads the session transcript, refuses tool calls at the threshold and clears the session itself.
- Starts a local page server on the Tailscale address, reachable by devices on that network.
Install
- Works in
Manual install
git clone https://github.com/alexknowshtml/claude-auto-handoff.git ~/claude-auto-handoffThen claude --plugin-dir ~/claude-auto-handoff; set CLAUDE_CODE_PLUGIN_DIRS for every session.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads the session transcript, refuses tool calls at the threshold and clears the session itself.
- Starts a local page server on the Tailscale address, reachable by devices on that network.
This is third-party code. Review the repository files before installing.
What it does
claude-auto-handoff watches Claude Code's context size. At the threshold the module refuses new tool calls, has Haiku write a structured brief to disk, runs `/clear` and sends the fresh session one line pointing at the brief. The fresh session reads the brief and keeps working. The brief has a fixed structure: work in progress, decisions, assumptions to verify, dead ends, the last request and whether it was answered, and the next step. File, commit and issue lists are assembled from the transcript in code, independent of the model's memory. A panel of steps is drawn above the prompt, and each brief gets a readable page served by a local server.
Who it is for. People running long Claude Code sessions who want to carry state into a fresh session in a controlled way instead of automatic compaction.
Good fit when
- A session of hundreds of thousands of tokens nears the window limit and work cannot stop.
- You want to edit the handoff brief by hand and its structure must stay fixed.
- You want to see how past attempts ended: dead ends and assumptions to verify are stored separately.
- Work runs from a phone and the brief page opens conveniently by a short link on a Tailscale network.
Not a fit when
- Your Claude Code build does not support mods (function-hook plugins): the plugin will not run on it.
- Auto-compact suits you and the structure of the brief does not matter.
- You cannot run an extra local server on the machine.
Example request
Set the handoff threshold to 80 thousand tokens for one run and show how the plugin writes the brief and clears the session.Limitations
A Claude Code build with mod support is required. The default threshold is 160000 tokens, sized for a 200k window, and it changes in settings or with the `AUTO_HANDOFF_TOKENS` variable for one run. Unmeasured tool output is estimated with headroom, so the real size sometimes lands under the threshold. If Haiku is unavailable the brief is built from facts only. The page server listens on the Tailscale address on port 3846 by default and uses 127.0.0.1 without Tailscale. The latest commit is from October 2026.
How to disable. Drop `--plugin-dir` from the launch command and the `CLAUDE_CODE_PLUGIN_DIRS` value from the environment or `~/.claude/settings.json`. `AUTO_HANDOFF_DISABLE=1` is enough for one session. Briefs in `~/.claude/state/auto-handoff/` are deleted by hand.
FAQ
Why is a handoff better than auto-compact?
Auto-compact summarises in place and you cannot control what it keeps. A handoff brief has a fixed structure you can edit, and file and commit lists come from the transcript in code.
Where are the briefs stored?
In `~/.claude/state/auto-handoff/<session-id>.md`, with readable pages in the `pages` subfolder.
How do I test without reaching 160 thousand tokens?
Set `AUTO_HANDOFF_TOKENS=60000` for one run. A seeded session starts near 45 thousand tokens, so values under about 85 thousand leave it little room.
What shows in the terminal during a handoff?
A panel above the prompt with steps: writing the brief, clearing and starting the new session. On success a line shows the context size before and after, for example 162k and 45k, with a link to the brief.
How do I load the plugin in every session?
Put the folder in the `CLAUDE_CODE_PLUGIN_DIRS` variable in the environment or in the `env` block of `~/.claude/settings.json`.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code plugin writes a handoff document while the session's prompt cache is still warm and costs stay low.
A Claude Code and Codex handoff plugin: a clean session with decisions and tasks kept, or history moved to the other client.
A Claude Code plugin that picks the model's effort level for every prompt and shows the prompt cache countdown
claude-history searches and opens past Claude Code, Codex and Pi conversations in the terminal and gives Claude a history skill
A Claude Code plugin that catches your corrections in chat and, after review, writes them into CLAUDE.md and AGENTS.md
Claude Code Toolkit (robertguss)
Claude Code Toolkit
A set of Claude Code skills and hooks: brainstorming, worker-led project leadership, a wiki, and a book pipeline.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| claude-auto-handoff (this card) | no | 125 | ||
| Context Mode | no | not required | 34,013 | saves context at the tool output level; claude-auto-handoff moves work into a fresh session at the threshold |
| Table Skills: project-handoff | no | 463 | skills for project handoff in tables; the plugin hands off the Claude Code session itself automatically |
README in short
The README walks through threshold, brief, clear and seed, panel, viewer page and an optional status line. The changelog reaches 0.8.3.