terryso/claude-auto-resume: a shell wrapper that waits out Claude CLI usage limits
A shell script utility that automatically resumes Claude CLI tasks when usage limits are lifted.
At a glance
- What is it?
- A single shell script that polls Claude CLI for a usage-limit message, sleeps until the reset timestamp, then relaunches your prompt with --dangerously-skip-permissions. Useful for unattended coding runs, risky everywhere else.
- Who is it for?
- Adopt it if you run long Claude Code tasks in a disposable container or VM and can tolerate prompts executing without confirmation. Skip it on any machine holding production credentials, customer data or an uncommitted working tree, because the script passes --dangerously-skip-permissions and will also run arbitrary shell commands given to -e.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 129 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap claude-auto-resume fills in a Claude Code session
Claude Code stops when the account hits its usage ceiling. The task is half done, the terminal sits at a prompt, and the reset may be an hour away. Someone has to come back and retype the instruction. claude-auto-resume exists so that nobody does.
The intended user is a developer running Claude Code on a long refactor, a test-writing pass or a build fix, who is willing to leave a terminal open and walk away. The README frames it around one concrete symptom: Claude Code printing `Claude usage limit reached.` while the task is unfinished. The script is also pitched for a second job, executing an arbitrary shell command once the wait is over, so a build or a service restart can be queued behind the same timer.
It is a small utility, and it is honest about being one. There is no daemon, no scheduler, no state file. One script, one process, one wait.
How the detection and resume loop actually works
The README describes a five-step cycle. First the script runs `claude -p 'check'` to probe the account. It then parses the output looking for a message in the form `Claude AI usage limit reached|<timestamp>`. If that pattern is present, it computes the remaining wait from the timestamp and prints a countdown. When the countdown finishes, it launches the real work.
That launch takes one of three shapes depending on flags. With no `-c`, it runs `claude --dangerously-skip-permissions -p "<prompt>"` as a fresh session. With `-c`, it adds the continue flag so the previous conversation is picked up. With `-e` or `--cmd`, it skips Claude entirely and runs the shell command you supplied.
The whole design rests on string matching against one message format. The repository carries four test scripts at top level (test_message_formats.sh, test_message_parsing.sh, test_unified_parser.sh, test-simulate-limit.sh), which suggests the author has been burned by format drift before and treats the parser as the fragile part. That is the right instinct: if Anthropic changes the wording or the timestamp layout, detection silently fails and the script proceeds as though no limit exists.
Installing claude-auto-resume and running a first resumed task
The README lists four Linux and macOS paths. The recommended one pulls the script straight from the develop branch and drops it on the system path, which means you are installing whatever is at the tip of that branch rather than a tagged release. The repository has no retrieved releases, so pinning is not an option here.
wget -qO- https://raw.githubusercontent.com/terryso/claude-auto-resume/refs/heads/develop/claude-auto-resume.sh | sudo tee /usr/local/bin/claude-auto-resume >/dev/null && sudo chmod +x /usr/local/bin/claude-auto-resumeIf you prefer to keep the source in a checkout, the Makefile installs it and accepts a different prefix. The `test` target only runs `bash -n` against the script, so it checks syntax, not behaviour.
sudo make install
sudo make install PREFIX=/opt/local
make testBefore letting it run unattended, check the environment and then exercise the wait path with a short simulated limit. The README lists `--check` for system information and `--test-mode` for simulating a usage limit with a wait time in seconds.
claude-auto-resume --check
claude-auto-resume --test-mode 5Once the countdown behaves, run it for real from the project root. The default prompt is `continue`, and `-c` resumes the prior conversation instead of opening a new one.
cd ~/projects/my-app
claude-auto-resume
claude-auto-resume -c "resume where we left off"
claude-auto-resume -e "npm run dev"On Windows the fork ships a PowerShell script and a `.cmd` wrapper. The README copies both into `$env:USERPROFILE\bin` and expects that directory to be on your user PATH; the wrapper prefers `pwsh` and falls back to Windows PowerShell.
$dest = Join-Path $env:USERPROFILE "bin"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item .\claude-auto-resume.ps1, .\claude-auto-resume.cmd $dest
claude-auto-resume --helpThe permission flag is the real cost of unattended resume
The README puts a security warning above everything else, and it should be read before the installation section. The script invokes Claude with `--dangerously-skip-permissions`, so Claude Code will not ask before editing files, running system commands or making code changes. Custom commands passed to `-e` run with no confirmation prompt of their own.
The practical consequence is that a vague prompt plus an unattended window equals unsupervised writes to your working tree. The README's own guidance points the same way: isolated development environments, avoid production systems and sensitive data, keep prompts specific to limit scope. Those are not boilerplate cautions; they describe the failure mode. If the resumed prompt is broad, the agent has hours to act on it.
There is a second, quieter limitation. The script depends on Claude CLI emitting a parseable limit message. The README documents exactly one format. Anything else (a network error, an authentication expiry, a differently worded quota notice) is not described as handled, and the README does not document retry or backoff behaviour for those cases either. Treat it as a tool for one specific interruption, not a general supervisor.
claude-auto-resume versus a plain retry loop
The obvious alternative is a shell loop you write yourself: run `claude -p "$prompt"`, check the exit status, sleep, try again. That approach does not need to know the limit message format, because it reacts to failure rather than parsing text. It also fails differently: a loop that retries on any non-zero exit will hammer the API during an outage and may re-run a prompt that already partially succeeded.
A second alternative is simply not automating at all and rerunning the command by hand after the reset. That costs you the wait time but keeps every execution supervised, which is the opposite trade-off from this project.
What claude-auto-resume adds over a naive loop is the timestamp-aware wait. Because it reads the reset time out of the limit message, the countdown reflects the actual window rather than a fixed sleep interval. That is a genuine improvement, and it is also the source of the fragility: the smarter behaviour is bought with a dependency on message text you do not control.
Maintenance, licence and what the repository does not promise
The last push to the repository was on 2026-05-09, and the default branch is develop, not main. The README's recommended install command fetches from that develop branch, so the code you install is whatever has most recently landed there. If you need reproducibility, use the Makefile against a checkout you control and pin the commit yourself, since no releases were retrieved.
The licence is MIT, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it says nothing about the security posture of the script, and MIT gives you no warranty. The permission-skipping behaviour is a design choice you accept, not a defect the licence covers.
Upgrade cost is low in the mechanical sense: re-run the wget line or `sudo make install` and the script is replaced. The real cost is re-verifying the parser after each upgrade, because the message format it matches is external. The four test scripts in the repository are the closest thing to a regression suite, and the README does not describe how to run them.
Editorial conclusion
Adopt it if you run long Claude Code tasks in a disposable container or VM and can tolerate prompts executing without confirmation. Skip it on any machine holding production credentials, customer data or an uncommitted working tree, because the script passes --dangerously-skip-permissions and will also run arbitrary shell commands given to -e. Before trusting it, run claude-auto-resume --check and claude-auto-resume --test-mode to confirm your Claude CLI version emits the limit message format the parser expects.
Frequently asked questions
What does a Claude generated resume look like?
The README does not describe generating a resume document. This project is a shell script that resumes an interrupted Claude CLI task after a usage limit is lifted, so the question does not apply to it.
How to use Claude to generate a resume?
The README does not cover resume-document generation. claude-auto-resume only detects a Claude usage limit, waits for the reset timestamp and then relaunches your prompt or a custom command.
Should you put Claude on your resume?
The README says nothing about listing Claude as a skill. Its subject is a script that resumes Claude CLI tasks after usage limits are lifted, so it cannot answer this.
Can Claude fix a resume?
The README does not address editing resume documents. The script's scope is detecting the Claude usage limit message, waiting out the reset and then running Claude or a custom shell command automatically.
Community notes