If you've been using Claude Code for any serious dev work, you've hit the wall: that dreaded "You've hit your limit · resets..." message. The standard recovery path—claude --resume or claude -c—is brutally inefficient. It dumps your entire conversation history back into context before you can even ask a follow-up question. For medium sessions, that's tens of thousands of tokens. Long sessions? Easily 100k+. You're burning through your usage window on pure overhead.

Enter handoff-revive

Developer sofumel just dropped a Show HN project that flips this problem on its head. Instead of replaying everything, handoff-revive extracts only the essential state needed to continue working and saves it to .claude/handoff/current.md. The file comes in at roughly 1–3k tokens—a fraction of what --resume would blast through. It captures your goal, completed/in-progress/todo tasks, the exact next action (file:line plus command), which files you touched and why, and any design decisions with their reasoning.

How It Works

The workflow is straightforward: when you're approaching a limit, run /handoff-revive:save. The skill detects your language (10 supported), pulls changed files from git status without prompting you, writes the structured handoff file using pure shell scripts that consume zero LLM tokens, and displays your estimated savings in chat. When the rate limit resets, start a fresh session—don't use --resume—and run /handoff-revive:resume. Claude reads only that one file and picks up where you left off. The plugin also hooks into Claude Code's usage tracking via rate_limits.five_hour.used_percentage. At 90% usage, it auto-saves a full handoff before your next response—zero interruption, no asking permission. At 95%, it saves again with an urgent notice. If you want checkpoint reminders based on turn count instead, the Stop hook nudges you every N turns (default: 15) to run a save.

Installation Options

The recommended path is Claude Code's plugin marketplace: /plugin marketplace add sofumel/claude-handoff-revive followed by /plugin install handoff-revive@handoff-revive-marketplace. This activates all skills, slash commands, and hooks automatically—no settings.json editing required. For those on older Claude Code versions or environments without plugin support, manual installation via git clone with an install script works across Linux, macOS, WSL, Git-Bash, and Windows PowerShell.

Strict Mode for Quality-Conscious Devs

If the basic save feels too loose, there's /handoff-revive:save-strict. After the regular save completes, Claude runs a semantic quality check: Is the goal specific enough that someone with zero context could understand it? Does each decision include an actual reason, not just restate what you did? Are blockers phrased as answerable questions? Is your work-in-progress state precise enough to resume mid-edit? Vague fields get rewritten automatically.

Token Math

The numbers are stark. Standard claude --resume: tens of thousands of tokens replayed, often 100k+. Standard claude -c: same story. handoff-revive: 1,000–3,000 tokens. You break even after just one save and one resume. Even if you save and never actually resume, the overhead is only a few kilobytes.

Key Takeaways

  • Stop using --resume after hitting limits—it wastes your context budget before you've done anything useful
  • handoff-revive reduces token reload from 100k+ down to 1–3k per session resume
  • Auto-save at usage thresholds means you won't lose work if you're not paying attention
  • Supports 10 languages including English, Japanese, Chinese, Korean, Spanish, Portuguese, German, French, and Turkish. MIT licensed, available now on GitHub.

The Bottom Line

This is exactly the kind of developer-tooling hack that should come baked into Claude Code itself—until Anthropic ships it, handoff-revive fills the gap elegantly. If you're burning tokens on context reloads instead of actual work, that's a solvable problem and this project solves it.