claude-handoff-plugin
Run /loop AFK for 8 hours without dying at 60% context.
A Claude Code plugin that watches your context window and, when an autonomous /loop session crosses threshold, automatically saves state and dispatches /clear + the resume command into the same terminal — so the fresh session picks up the loop where the previous one left off. No human at the keyboard required.
Demo TODO: record cmux / Claude Code window mid-/loop, hook detects ctx ≥60%, watch the pane swap to a fresh session that resumes /loop verbatim. Drop the GIF at docs/handoff-demo.gif.
Why this exists
If you run /loop AFK — atomic-ticket queues, overnight CI grinding, autonomous-loop sentinels — the session eventually fills Claude Code's context window. The fix is well-known: summarize, /clear, re-invoke /loop with the same prompt. But that fix needs a human at the keyboard at exactly the right moment, which defeats AFK.
This plugin makes the fix automatic. A UserPromptSubmit hook reads context% from a sidecar (claude-hud writes one for free; any statusline can write ~/.claude/context_pct.json). At threshold, in /loop mode, with a clean tree + pushed commits + PR gate green, it writes ~/.claude/handoff_last.json and fires keystrokes via cmux / tmux / screen / OS-native automation. The fresh session reconciles the saved prompt against the new git HEAD and re-invokes /loop verbatim.
Not for you if you only use Claude Code interactively. Auto-fire is gated to /loop AFK mode; interactive sessions get a reminder, not a takeover. Manual /handoff:handoff works in either, but /clear is destructive — only use when you're done with the current conversation.
Install
/plugin marketplace add miaojan/claude-handoff-plugin
/plugin install handoff
Use
When context is high (≥60%) and your current commit is pushed + CI-green:
/handoff:handoff
The skill:
- checks
git status and unpushed commits in the current cwd,
- runs the PR cleanup gate (queues open PRs for auto-merge / blocks on red CI / conflicts),
- writes
~/.claude/handoff_last.json (git HEAD, cwd, the verbatim /loop prompt, cmux pane IDs if any),
- detaches an auto-restart helper that fires
/clear then /handoff:handoff-resume into the same Claude Code window.
In the fresh session, handoff-resume reads the state, reconciles the prompt against the current HEAD, marks the file as serviced, and re-invokes /loop verbatim.
How auto-restart picks a backend
The helper probes backends in order and uses the first one that's available. Each backend ships as a small script in scripts/pane-sender/ with a uniform --available self-test.
| order | backend | requires | platform | tested |
|---|
| 1 | cmux | cmux CLI + CMUX_WORKSPACE_ID/SURFACE_ID | macOS | yes |
| 2 | tmux | tmux CLI + $TMUX | macOS, Linux | blind |
| 3 | screen | screen CLI + $STY | macOS, Linux | blind |
| 4a | AppleScript | osascript | macOS | yes |
| 4b | xdotool | xdotool + $DISPLAY (X11) | Linux X11 | UNTESTED |
| 4c | wtype | wtype + $WAYLAND_DISPLAY | Linux Wayland | UNTESTED |
| 4d | SendKeys | PowerShell + System.Windows.Forms | Windows | UNTESTED |
If all backends fail, the helper logs "manual /clear + /handoff:handoff-resume needed" and exits — the state file is intact, you can resume by hand. The Linux/Windows pathways are best-effort and have not been validated end-to-end. PRs / issues welcome.
Auto-handoff at threshold (UserPromptSubmit hook)
The plugin ships a UserPromptSubmit hook (hooks/context-pct-guard.sh) that runs on every prompt submission. Below threshold it prints a ctx X% readout to stdout (visible in Claude's system reminders, useful for self-judging context budget). At or above threshold it diverges by mode:
- Interactive session (current prompt is NOT a
/loop): emit a user-facing reminder to type /handoff:handoff once the current commit is pushed + CI-green. Does NOT auto-fire — interactive users should keep control.
/loop AFK mode (current prompt starts with /loop or is one of the autonomous-loop sentinels): pre-flight (clean tree + pushed + PR gate green) → auto-fire writer + auto-restart in background. The next prompt of this session is wiped by /clear and the fresh session resumes from /handoff:handoff-resume. If pre-flight fails, inject a directive to finish the current atomic and try again on next /loop re-entry.
