claude-handoff-revive

Continue Claude Code work after a rate / usage / context limit without replaying your prior session — typically tens of thousands of tokens, often 100k+ for long sessions.

🇺🇸 English · 🇯🇵 日本語 · 🇨🇳 中文 · 🇹🇼 繁體中文 · 🇰🇷 한국어 · 🇪🇸 Español · 🇵🇹 Português · 🇩🇪 Deutsch · 🇫🇷 Français · 🇹🇷 Türkçe

Contributing · License (MIT)

---

🇺🇸 English

The problem

When Claude Code shows You've hit your limit · resets ..., the standard recovery — claude --resume or claude -c — reloads the entire prior conversation into context. A medium session typically burns tens of thousands of tokens, often 100k+ for long sessions, before you've asked a single question.

What this skill does

It saves only the minimum needed to continue, structured into .claude/handoff/current.md (~1–3k tokens):

• goal — what you were trying to accomplish
• done / wip / todo — completed, in-progress, not-yet-started tasks
• next_action — the concrete next step (file:line + exact command)
• touched_files — what files were touched and why
• decisions — design choices, with the reason behind each
• lessons_learned — failed attempts and what they taught (optional)

To resume, start a new session (don't use --resume). The skill reads only that one file and picks up where you left off.

Install

Plugin install (recommended) — run these inside Claude Code:

/plugin marketplace add sofumel/claude-handoff-revive       # 1. register marketplace
/plugin install handoff-revive@handoff-revive-marketplace   # 2. install plugin

Skill, slash commands, and hooks auto-activate. No settings.json editing required.

/plugin isn't available in this environment? Your Claude Code version is too old. Check with claude --version and update via brew upgrade claude-code (Homebrew) or npm update -g @anthropic-ai/claude-code (npm). If you can't update, use the manual install below.

Manual install (always works, no plugin support required):

git clone https://github.com/sofumel/claude-handoff-revive.git
cd claude-handoff-revive
./install.sh /path/to/your-project        # Linux/macOS/WSL/Git-Bash
# .\install.ps1 -Target C:\path\to\proj   # Windows PowerShell

# Or globally for all projects:
./install.sh --global       # .\install.ps1 -Global

For the manual install, optionally enable hooks by merging the snippet from HOOK_SETUP.md into your .claude/settings.json (the plugin install does this automatically).

Should .claude/handoff/ be committed to git? Both work — pick one deliberately:

• Solo use (default) — ignore it all; volatile state and snapshots don't belong in history:

  .claude/handoff/
  

• Team sharing — commit only the current handoff; keep snapshots and marker files local:

  .claude/handoff/*
  !.claude/handoff/current.md
  

Never commit the dot-marker files (.turn, .usage-flag, …) or history/ — they are machine-local state and snapshot noise.

How to use

Quick reference:

Action	Type this in Claude Code
Save handoff	/handoff-revive:save
Resume in a NEW session	/handoff-revive:resume
Preview what the next session will read	/handoff-revive:preview
List saved snapshots	/handoff-revive:list
Restore a past snapshot	/handoff-revive:restore <timestamp>
Diff current vs a past snapshot	/handoff-revive:diff [timestamp]
Post the handoff to a PR as review context	/handoff-revive:share-to-pr [PR] (needs gh)
Show save/resume stats	/handoff-revive:stats
Diagnose the installation	/handoff-revive:doctor
Switch handoffs when changing branch	/handoff-revive:switch
Toggle auto-save for this session	/handoff-revive:auto on / off / status

When sharing to a PR, the body is built from a sanitized copy: the author_email line is removed, absolute project/home paths become <project-root> / ~, and known-prefix API keys/tokens (e.g. sk-, ghp_, AKIA, private-key blocks, JWTs) are scanned — if any are detected the post is aborted (nothing is ever silently redacted). Sanitization is best-effort, not a security guarantee: generic passwords and unprefixed random strings are NOT detected; reviewing the preview remains your responsibility.

Step 1 — when you're approaching a rate limit, save

In Claude Code, type the following command:

/handoff-revive:save

Behind the scenes, the skill runs these steps automatically (all zero-LLM-token where possible):

1. Detects your language (10 supported: en / ja / zh / zh-TW / ko / es / pt / de / fr / tr) from your message
2. Pulls changed files from git status — you don't have to remember which files you edited
3. Writes a schema-conformant handoff to .claude/handoff/current.md
4. Validates the schema, cleans up dead paths, strips empty sections — pure shell, no tokens
5. Displays the estimated savings in the chat

Step 2 — wait for the rate limit to reset

When the time on resets ... passes, your usage window opens again.

Step 3 — start a NEW session (do NOT use --resume)

claude

When the new session starts, the plugin automatically detects the recent handoff. Just run:

/handoff-revive:resume

Claude reads only that one small file and picks up right where you left off — no need to replay the whole conversation.

Optional: turn-count nudge (off by default)

A periodic reminder to checkpoint. It is off by default — enable it by setting HANDOFF_CHECKPOINT_EVERY to the number of turns between reminders (e.g. 15):

export HANDOFF_CHECKPOINT_EVERY=15

When enabled, every N turns Claude prints:

[handoff-revive] Turn 15 — checkpoint due. Run /handoff-revive:save to save.

Auto-save at 90% / 95% usage (synced with the UI notification)

The usage-monitor hook (PostToolUse) reads rate_limits.five_hour.used_percentage — the same value that drives Claude Code's "approaching usage limit" notification. When you cross 90%, Claude auto-saves a full handoff before its next response (no asking, no interruption). At 95%, it saves again with an urgent notice.

Per-session opt-out if you don't want auto-save in the current thread:

/handoff-revive:auto off       # disable for THIS session
/handoff-revive:auto on        # re-enable
/handoff-revive:auto status    # show current state + thresholds

/handoff-revive:auto off only affects the current session — a new session is back to ON. To turn auto-save off permanently, set these as environment variables in your shell profile (e.g. add to ~/.zshrc or ~/.bashrc, then open a new terminal):

export HANDOFF_AUTO_SAVE_PERCENT=disabled
export HANDOFF_URGENT_PERCENT=disabled

To shift the thresholds instead of disabling, set HANDOFF_AUTO_SAVE_PERCENT=80 (fires earlier) the same way, or configure them per-hook in settings.json (see HOOK_SETUP.md).

Token budget

Method	Tokens replayed to resume
claude --resume	tens of thousands, often 100k+
claude -c	tens of thousands, often 100k+
handoff-revive	1,000–3,000

Under the hood (automatic, zero-token)

Every save and resume runs these in pure shell — no extra input, no tokens:

• Sharing metadata — each save injects author, branch, base_commit, created_at into the frontmatter, so a teammate (or future you) can see who saved it, on which branch, from which commit. HANDOFF_HIDE_EMAIL=1 omits the email.
• Freshness check on resume — compares that metadata against your current git state and warns when the handoff is N commits behind or on a different branch. It also warns when the file is older than HANDOFF_STALE_DAYS (default 7; 0 disables) — the age check needs no git, so it works in plain directories too. Purely informational; it never blocks the resume.
• Snapshot history — each save also archives a copy to .claude/handoff/history/<timestamp>.md. /handoff-revive:list shows them, /handoff-revive:restore <timestamp> brings one back (non-destructive — the current handoff is archived first), /handoff-revive:diff [timestamp] compares. Snapshots past HANDOFF_HISTORY_RETENTION_DAYS (default 30) are pruned automatically. A snapshot is the structured work state, not the conversation history.

Relationship with CLAUDE.md

They answer different questions — don't write the same thing into both:

	CLAUDE.md	handoff (current.md)
Holds	durable project knowledge: conventions, architecture, commands	volatile work state: current goal, WIP, next action
Lifetime	months (changes rarely)	hours–days (overwritten per save, snapshotted to history)
Loaded	every session, always	only when resuming via /handoff-revive:resume

Writing work state into CLAUDE.md taxes every future session with stale context; keeping it in the handoff costs nothing until you actually resume. Opt-in helper (appends a one-line guidance comment to CLAUDE.md, idempotent, never edits existing content):

bash .claude/skills/handoff-revive/scripts/setup-claude-md.sh

License

MIT — see LICENSE.

Privacy — see PRIVACY.md: everything runs locally. No data leaves your machine unless you run /handoff-revive:share-to-pr yourself.

---

🇯🇵 日本語

解決する問題

You've hit your limit · resets ... という制限通知が表示された後、claude --resume や -c で再開すると、それまでの会話履歴がまるごとコンテキストに再ロードされます。中規模のセッションでも数万トークン、長いセッションでは 10 万を超えるトークン分が、まだ何も質問していない段階で消費されてしまいます。

この skill が提供するもの

作業の続きに必要な最小限の情報だけを構造化して .claude/handoff/current.md に保存します（約 1〜3k トークン）。保存される項目:

• goal — 何を達成しようとしていたか