# claude-auto-resume: Automatic Task Continuation When Claude Code Hits Its Usage Limit

> claude-auto-resume is a shell script that detects when Claude Code's usage limit has been reached, waits for the reset timestamp the CLI prints, and then re-invokes Claude automatically with the original prompt or a custom command. It solves the interruption problem for long-running development sessions without requiring any third-party dependencies.

**terryso/claude-auto-resume** — A shell script utility that automatically resumes Claude CLI tasks when usage limits are lifted.

- Repository: https://github.com/terryso/claude-auto-resume
- Website: https://gptkit.eth.limo/
- Stars: 823 · Forks: 66
- Language: Shell
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/terryso-claude-auto-resume

## The Problem It Solves: Interrupted Claude Code Sessions

Claude Code imposes usage limits that interrupt long-running tasks with a 'Claude usage limit reached' message containing a timestamp. When this happens mid-task, the developer must check manually, wait, then re-issue the command. For a complex refactor or a test-writing session that might span multiple limit cycles, this is an interruption that can break context and focus.

claude-auto-resume automates the wait-and-resume cycle. It runs the Claude CLI, detects the usage limit message, extracts the reset timestamp, counts down to that moment, and then re-invokes Claude. The developer starts the script and can step away. When the limit lifts, Claude Code picks up automatically.

The project also covers a second use case: executing any arbitrary shell command after a waiting period, using the same countdown mechanism. This is useful for restarting services or triggering builds at a specific future time without writing a separate cron job.

## How the Detection and Wait Mechanism Works

The script's core behaviour follows a five-step sequence. First, it runs `claude -p 'check'` to probe for a limit message. Second, it looks for the pattern `Claude AI usage limit reached|<timestamp>` in the output. Third, it calculates how many seconds remain until the timestamp. Fourth, it displays a real-time countdown. Fifth, it executes the resume command automatically.

For Claude Code tasks, the resume command is `claude --dangerously-skip-permissions -p "<your prompt>"` by default, or `claude -c --dangerously-skip-permissions -p "<your prompt>"` when the -c flag is passed to continue the previous conversation thread. The `--dangerously-skip-permissions` flag is necessary for unattended execution because it bypasses Claude's normal permission prompts.

The README prominently warns about this flag: Claude Code will execute tasks without asking for permission, file operations will run automatically, and system commands will execute without user confirmation. The project recommends using the script only in isolated development environments and avoiding it on production systems or with sensitive data.

## Installation on Linux, macOS, and Windows

The script has four installation methods. The simplest for Linux and macOS is a one-line wget command that downloads the script and places it in /usr/local/bin:

```bash
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-resume
```

The Makefile method supports custom installation prefixes:

```bash
sudo make install
```

A manual copy also works:

```bash
sudo cp claude-auto-resume.sh /usr/local/bin/claude-auto-resume
sudo chmod +x /usr/local/bin/claude-auto-resume
```

For Windows, the repository includes a PowerShell script and a .cmd wrapper. Copying both files to a directory on the user PATH and running `claude-auto-resume --help` verifies the installation. The .cmd wrapper invokes pwsh if available and falls back to Windows PowerShell.

The script requires only standard Unix tools and has zero external dependencies. All four methods are described in the README.

## Running the Script and Its Command-Line Options

With no arguments, claude-auto-resume starts a new Claude session and sends the prompt 'continue' when the limit resets. This is the simplest recovery pattern for a task that was already in progress and left context in the working directory.

To specify a different prompt:

```bash
claude-auto-resume "implement user authentication"
```

To continue the previous conversation thread rather than starting a fresh session:

```bash
claude-auto-resume -c "please continue the previous task"
```

To execute an arbitrary shell command after the wait instead of re-invoking Claude:

```bash
claude-auto-resume -e "npm run dev"
```

Other flags include --test-mode for simulating a usage limit in development, --check for viewing system information, -v for version, and -h for help. The full flag list is documented in the README under Command Line Options.

## Genuine Limitations and When Not to Use It

The most significant limitation is the security model. Every execution of the automated Claude task runs with --dangerously-skip-permissions, which means Claude Code can modify files, run shell commands, and execute code without pausing for confirmation. If the original prompt is broad or ambiguous, the automated continuation may take actions the developer did not anticipate. The README's recommendation to 'be specific with your prompts to limit scope of actions' is a real constraint, not a disclaimer to ignore.

The script also depends on the specific format of Claude's usage-limit message. If Anthropic changes the output format of the `Claude AI usage limit reached|<timestamp>` string, the parsing logic may fail silently or misinterpret the wait time. The repository has no automated tests that validate against live Claude output, though the Makefile includes a `make test` target that checks the script's syntax with `bash -n`.

The last push to the repository was on 2026-05-09. There are no GitHub releases and no versioned packages. The develop branch is the default branch.

## Comparison with Scheduling Alternatives and License

The most obvious alternative is a cron job or a system-level task scheduler. The difference is that cron fires at a fixed time, not at the moment the Claude limit actually resets. If the reset happens earlier or later than expected, a cron job either fires too early (limit still active) or adds unnecessary delay. claude-auto-resume reads the actual reset timestamp from Claude's output and waits only as long as necessary.

For teams running Claude Code in CI pipelines or headless environments, the script's zero-dependency design is an advantage. It requires only bash and standard Unix tools on Linux and macOS, or pwsh/Windows PowerShell on Windows. There is nothing to install beyond the script itself.

The project is released under the MIT license, which permits unrestricted use, modification, and redistribution. A CLAUDE.md file is present in the repository, indicating the project itself uses Claude Code for development work.

## Conclusion

claude-auto-resume is the right tool for developers running extended Claude Code sessions who are comfortable with the security implications of --dangerously-skip-permissions. Anyone working on a production system, with sensitive data, or in an environment where unattended file writes or shell commands are unacceptable should not use it. Before running the script, read the README's security warning in full and confirm that your prompt is specific enough to limit the scope of what Claude will execute during the automated continuation.

## FAQ

### Does claude-auto-resume work with the -c flag to continue a previous conversation?

Yes. Passing -c to claude-auto-resume makes the script use `claude -c --dangerously-skip-permissions` when resuming, which continues the previous conversation thread rather than starting a new session.

### What are the security risks of claude-auto-resume?

The script invokes Claude Code with --dangerously-skip-permissions, which means file writes, shell commands, and code changes will run without user confirmation. The README warns to use it only in isolated development environments and not on production systems or with sensitive data.

### Can claude-auto-resume run a shell command instead of resuming Claude Code?

Yes. The -e or --execute flag takes any shell command and runs it after the wait period instead of invoking Claude. The --cmd flag is an alias for the same behavior.

## Sources

- [Issues](https://github.com/terryso/claude-auto-resume/issues)
- [License: MIT](https://github.com/terryso/claude-auto-resume/blob/develop/LICENSE)
- [Project website](https://gptkit.eth.limo/)
- [README](https://github.com/terryso/claude-auto-resume/blob/develop/README.md)
- [terryso/claude-auto-resume on GitHub](https://github.com/terryso/claude-auto-resume)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/terryso-claude-auto-resume