GitHub - softcane/cc-session-recover: Recover Claude Code sessions after quota or rate-limit stops. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
softcane
cc-session-recover
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>11 Commits<br>11 Commits
.claude
.claude
.github/workflows
.github/workflows
bin
bin
docs
docs
scripts
scripts
.gitignore
.gitignore
CHANGELOG.md
CHANGELOG.md
HANDOFF.md
HANDOFF.md
LICENSE
LICENSE
README.md
README.md
SECURITY.md
SECURITY.md
package-lock.json
package-lock.json
package.json
package.json
View all files
Repository files navigation
cc-session-recover
Your long Claude Code task survives quota stops — and continues by itself after the reset, with no prompt from you.
When quota or a rate limit kills a session mid-task, Claude normally just stops until you come back and tell it to continue. This workflow removes that. Claude keeps a recovery note (HANDOFF.md) as it works, retries on a slow schedule while quota is blocked, and the first attempt after the reset picks the task up exactly where it stopped.
Every part of this has been verified against a genuine quota stop, end to end.
Install
npx cc-session-recover init /path/to/project
(Or from a clone: bash scripts/install-into-project.sh /path/to/project. Pass --no-hooks with either to install the files without activating anything.)
Approve the hooks once when Claude Code asks on the next start. That's the whole setup.
Use
cd /path/to/project<br>claude
Give Claude your task, normally. Nothing extra to type — the injected standing instructions make Claude keep the recovery note and set its own retry schedule. Leave the terminal open and walk away.
If quota dies mid-task, work resumes automatically after the reset.
Why This Approach Is Stronger
It avoids tmux, screen, and terminal-injection hacks. Headless claude -p --resume is used only by the optional closed-terminal watcher, targeting the exact recorded session.
It gives you two recovery paths. With the terminal open, the heartbeat resumes inside the active Claude Code session. With the terminal closed, the watcher resumes the saved session id.
HANDOFF.md keeps the next step in the repo, with project state, recent progress, and the exact next action.
The heartbeat runs inside the active Claude Code session, so the original context stays alive while quota is blocked.
Limits
It does not bypass quota. It only waits for the reset.
The basic flow needs the terminal to stay open. A closed-terminal recovery mode exists; see the docs.
Worst case is never lost work: the recovery note is always on disk, and "Read HANDOFF.md and continue" restores any session by hand.
Docs
Simple flow — how it works, told as a story (notebook, alarm, watchman).
FAQ — reliability, hook approval, what still needs a human.
Full details — closed-terminal watcher, precise reset-time resume, all limits.
About
Recover Claude Code sessions after quota or rate-limit stops.
Topics
resume
hooks
rate-limit
quota
claude-code
session-recovery
Resources
Readme
License
MIT license
Security policy
Security policy
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
stars
Watchers
watching
Forks
forks
Report repository
Releases
v0.1.5
Latest
Jun 13, 2026
+ 4 releases
Packages
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Shell<br>80.0%
JavaScript<br>20.0%
You can’t perform that action at this time.