handoff-revive

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 30,000–200,000 tokens 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

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).

How to use

Quick reference:

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

In Claude Code, type the following command:

/handoff

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)