claude-auto-retry: waiting out Claude Code rate limits from the terminal

The gap claude-auto-retry fills, and who is standing in it

Claude Code stops when a subscription limit is reached. The README gives the render as `You've hit your limit · resets 3pm (Europe/Dublin)`. The session sits at a prompt. Nothing resumes until a human types "continue". For an interactive session where you are watching the screen, that is a minor annoyance. For an overnight job, an always-on agent, or an SSH session you walked away from, it is a dead stop that can cost the rest of the night.

The README is explicit about the current state of the problem. As of its August 2026 status note, the Claude Desktop app has a native "Auto-continue when limits reset" checkbox, confirmed in a linked claude-code issue comment. The CLI does not. The README frames that asymmetry as the reason the tool exists and points at anthropics/claude-code#35744 for the native CLI version. That is an honest framing, and it is also the main risk to the project: if the CLI gains the checkbox, the tool's reason to exist narrows to the extra cases it also handles, which are API overload backoff, safeguard false positives, and interrupted-stream resume.

The audience is narrow and specific. People who drive Claude Code from a terminal, who run it on a remote box, and who are willing to let a wrapper change how the process is launched.

Shell function, tmux session, and a five-second poll

The mechanism is a shell function injected into `.bashrc` or `.zshrc`. When you type `claude`, the function takes over. If you are already inside tmux, it starts a background monitor and launches Claude with its full TUI in the current pane. If you are not, it creates a tmux session transparently, launches Claude and the monitor inside it, and attaches you. From your side the screen looks unchanged.

The monitor polls the tmux pane every 5 seconds, which the README describes as roughly 0% CPU. It matches the pane text against the verbatim renders listed in the README: N-hour limits, session limits, weekly limits, usage limits, out-of-extra-usage, "Please try again in 5 hours", and a rate-limit form. When it matches, it parses the reset time, including IANA timezone names and half-hour offsets, and waits until that time plus a 60-second margin. Before injecting anything it verifies Claude is still the foreground process, then sends "continue" with `tmux send-keys`.

tmux is the load-bearing choice, not a convenience. If your SSH connection drops or your laptop sleeps, a plain wrapper script dies with the terminal. A tmux session survives, so the monitor keeps waiting and you reattach later to find the work advanced. The README names that as the key advantage over wrapper scripts, and it is the one design decision that explains most of the rest of the architecture.

The `/rate-limit-options` menu gets separate handling. The README says option order varies by Claude Code version, so the tool locates the cursor and the "Stop and wait" entry rather than pressing a fixed key. It refuses to press Enter if the layout is unreadable. That refusal is the right default: guessing on a menu whose first entry is "Upgrade your plan" would be expensive.

Installing claude-auto-retry and your first unattended run

The README gives a two-command install. The package is global, so the binary lands on your PATH.

npm i -g claude-auto-retry
claude-auto-retry install

The first command installs from npm; Node.js 18 or newer is required, per the `engines` field in `package.json`. The second writes the shell function into your rc file. Open a new shell or source the file afterwards. The README notes the tool auto-installs tmux if it is missing, using apt, dnf, brew, pacman or apk depending on the platform.

After that you type `claude` exactly as before. To confirm the wrapper is in play, start a session and check the tmux status bar. The README describes an indicator that distinguishes being monitored, waiting on a reset, backing off from overload, and having given up. The status script is exposed as a second binary, `claude-auto-retry-tmux-status`, per `package.json`.

If a monitor goes missing from a live session, the README documents a reconcile path that re-arms monitors for any running `claude` session that lost one. It can be run automatically by a user-level timer: `systemd --user` on Linux, launchd on macOS. The repository ships `systemd/` and `launchd/` directories for those units.

Configuration is validated. The README states that bad config values fall back to safe defaults rather than crashing, which matters when the config controls how long the tool waits and how many times it retries.

Overload backoff, safeguard retries, and the near-limit nudge

Three behaviours sit outside the simple wait-for-reset path, and they are where the tool earns its keep beyond the Desktop checkbox.

The first is overload backoff. The README lists `429/500/502/503/504/529` as the codes it treats as sustained API overload, and says it retries on a configurable exponential backoff with jitter and a cumulative-wait cap. This is a different path from the usage-reset wait: there is no printed reset time to parse, so the retry schedule is generated rather than derived. The cumulative cap is the important part. Without it, a long outage turns into an unbounded retry loop.

The second is safeguard retry. When an AUP-safeguard flag fires as a false positive, the README says the tool auto-continues past it, capped at a few tries so a sticky flag cannot loop. That cap is the correct call. A false positive is often transient; a real flag is not, and a retry loop against a real flag just burns attempts.

The third is the near-limit wrap-up nudge. Claude Code can wind a turn down at roughly 95% of the 5-hour window with a message the README renders as "Approaching your 5-hour usage limit - Claude will wrap up the current step", then park at an idle prompt with no limit banner. In that state there is nothing for the reset parser to read. The tool sends one `continue` so the work runs on to the actual limit, where the normal usage wait takes over. One nudge, not a loop.

There is also interrupted-stream resume, which the README describes as picking work back up when a laptop suspend or dropped connection truncates a response mid-turn and leaves the session at an idle prompt.

Where claude-auto-retry is the wrong tool

The README's own status note is the biggest limitation. The Desktop app already has native auto-continue. If you work in the Desktop app, this tool does nothing for you. If the CLI gains the checkbox tracked in anthropics/claude-code#35744, the remaining value is the overload, safeguard and interrupted-stream paths, which the README does not claim the native feature covers.

Text matching is inherently brittle. The detector acts on verbatim renders, and the README publishes the table precisely because the tool depends on those strings. Anthropic can reword a banner, change a menu layout, or localise output, and the match fails silently. The README does say the `/rate-limit-options` handler copes with varying option order and refuses to press Enter on an unreadable layout, which is a partial defence, but the banner table itself is a fixed list. If your Claude Code prints something not in that table, the monitor waits forever.

The tmux requirement is a real constraint even though the README calls it transparent. Your `claude` command now runs inside a tmux session. Anyone with a workflow built around terminal multiplexers, nested sessions, or terminal emulators that interact badly with tmux will feel that. The tool also modifies your shell rc file, which is a persistent change to your environment, and the README does not document a rollback or uninstall path.

Finally, the polling design means up to 5 seconds of latency between the banner appearing and the monitor noticing. That is fine for a wait measured in hours and irrelevant for the overload path, but it is not a zero-latency reaction.

How it differs from a hand-rolled retry wrapper

The obvious alternative is a short wrapper script of your own: run `claude`, capture output, `grep` for a limit string, sleep, send a keystroke. Many people have written one. The difference is what happens when the session is not attached.

A wrapper script lives and dies with its parent shell. Close the terminal, drop the SSH connection, or let the laptop suspend, and the script is gone along with the Claude process it was supervising. claude-auto-retry sidesteps that by making tmux the process owner. The monitor and Claude both live in the tmux session, so the supervision outlives the client. Reattaching with `tmux attach` returns you to a session that kept working. That is the whole argument for the tmux dependency, and it is a stronger argument than the README's brevity suggests.

The second difference is coverage. A hand-rolled grep handles the usage-limit case. It does not handle the `/rate-limit-options` menu with its version-varying option order, the near-limit wrap-up nudge where there is no banner to match, or the cumulative-wait cap on overload backoff. Each of those is a separate failure mode that the README documents as handled.

The third is maintenance surface. A wrapper script is yours to fix when Anthropic changes a string. claude-auto-retry is a published package with releases, a changelog and a test directory, so string changes are someone else's problem, at least while the project keeps shipping. The trade is that you now depend on a third-party tool sitting between you and your CLI.

Licence, upkeep, and what a version bump costs you

The licence is MIT, declared in `package.json` and shipped as a `LICENSE` file. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are retained. That is the general shape of the licence, not legal advice for your situation.

The repository is not archived, and the last push was on 2026-08-26, which is recent enough that describing it as maintained is defensible on the evidence available. The release history supports that: v0.7.1 on 2026-08-14, v0.7.2 and v0.7.3 on 2026-08-16. Three releases in three days suggests active iteration rather than a one-off publish, though the README's own status note points at a native CLI feature that would shrink the project's scope.

Upgrade cost is low by construction. The package has zero dependencies and no `node_modules`, so a version bump does not drag a dependency tree with it. The runtime requirement is Node.js 18 or newer. The published files are `bin/`, `src/`, `systemd/`, `launchd/`, `LICENSE`, `README.md`, `CHANGELOG.md` and `llms.txt`, so the install footprint is small and the changelog is present for reading before you upgrade.

The one upgrade risk is the shell function. It is written into your rc file at install time, so a new version that changes the injection needs the install step re-run. The README does not document an upgrade procedure, which is worth knowing before you assume `npm i -g` alone is sufficient.

Editorial conclusion

Adopt claude-auto-retry if you run Claude Code from the CLI, especially over SSH or on long unattended tasks, and you are willing to have your shell function route through tmux. Skip it if you use the Claude Desktop app, which the README says now has a built-in auto-continue checkbox, or if you cannot accept a background process polling a pane every 5 seconds. Before installing, check three things on your own machine: that tmux is present or installable by your package manager, that `claude-auto-retry --help` lists a `reconcile` subcommand in your installed version, and that your Claude Code renders the limit banner in one of the forms the README lists verbatim. If your banner text is not in that table, the detector has nothing to match.

Frequently asked questions

Official sources

1. cheapestinference/claude-auto-retry on GitHub
2. Issues
3. License: MIT
4. README
5. Releases