# claude-auto-retry: a tmux monitor that waits out the five-hour limit for you

> The project wraps your claude command in a shell function that hands the session to tmux, then runs a background monitor which reads the limit banner, waits for the printed reset, and types continue. Several failure modes get their own separate code paths.

**cheapestinference/claude-auto-retry** — Auto-retry Claude Code on subscription rate limits, API overload (529/5xx) and safeguard false positives — waits for the printed reset, exponential backoff, tmux-based

- Repository: https://github.com/cheapestinference/claude-auto-retry
- Stars: 380 · Forks: 73
- Language: JavaScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/cheapestinference-claude-auto-retry

## A shell function takes over the word claude, and tmux keeps the session alive

Installation is two commands, and neither of them tells you to change how you work:

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

What that install does is inject a shell function into .bashrc or .zshrc, so the next time you type claude the function intercepts before the real binary runs. The function checks whether you are already inside tmux. If you are, it starts a background monitor and launches claude with the full TUI you are used to. If you are not, it creates a tmux session transparently, runs claude and the monitor inside it, and attaches, which is why the session looks unchanged from the outside.

The tmux layer is the load bearing decision rather than a convenience. When an SSH connection drops, a terminal window closes, or a laptop suspends, the claude process inside a tmux session survives. The monitor survives with it and keeps counting down to the reset. Reconnect and attach, and the work is still running. A plain wrapper script around the command would die with the shell. The README is explicit that this is the advantage over wrapper scripts, and the tool will install tmux itself through apt, dnf, brew, pacman, or apk when it finds it missing.

## The monitor reads the printed reset time rather than guessing a window

The loop the monitor runs is short. It polls the tmux pane every five seconds, scans for limit text, parses the reset time out of the message, and then sleeps until that time plus a safety margin. The reason it parses the printed time instead of assuming a five-hour window from the moment it noticed is that the limit message carries an explicit clock time, and a monitor that computed its own deadline from first sight would drift whenever it started late.

The set of strings it recognises is broad because the renders changed over time. The listed forms include a bare N-hour line such as `5-hour limit reached - resets 3pm (UTC)`, the session variant `You've hit your session limit · resets 2am (Europe/Zurich)`, a weekly line with a date in it such as `You've hit your weekly limit · resets Oct 9, 10am`, a sentence form like `Claude usage limit reached. Resets at 2pm`, an extra-usage line, a `Please try again in 5 hours` render, and a bare `Rate limit hit. Resets at 4pm`. One more entry is a companion hint rather than a limit banner: the line suggesting `/usage-credits` to finish what you are working on.

The timing is timezone aware and handles half-hour offsets, and it corrects for daylight saving transitions iteratively rather than applying a fixed offset. After the wait, one more check happens before anything is typed: the tool verifies claude is still the foreground process in that pane. It will not send keys into a pane where the foreground program has changed.

## The rate limit menu is driven to the waiting option, and refused when unreadable

Some limit states do not just stop the session, they present a choice. The render the project documents is a two item menu asking what you want to do, with upgrade your plan as the first entry and stop and wait for limit to reset as the second:

```
What do you want to do?
❯ 1. Upgrade your plan
  2. Stop and wait for limit to reset (3pm)
```

The tool handles this by driving the menu to the waiting option. It locates the cursor position and finds the stop and wait entry, then confirms that selection. The ordering is not fixed across Claude Code versions, so the handling is written against any menu layout rather than against positions. The safety rule is the interesting part: if the layout cannot be read, the tool refuses to press Enter. A misread menu on a billing screen is worse than a missed retry, and the code is built to fail toward doing nothing.

That same principle shows up in the send-keys path. Injecting text into a tmux pane is indistinguishable from a human typing, so the check on the foreground process is the only guard against sending continue to a shell, an editor, or a different program that happens to occupy the pane after claude exited.

## Overload gets a backoff path, not a wait-until-reset path

Two problems that look similar to a user are handled by different code, and keeping them apart is what stops the tool from sleeping for hours when the server is merely busy. The first is API overload and transient server failure, and it is recognised as a 429 at the API level, the 5xx family of 500, 502, 503, and 504, and the 529 status that Anthropic returns during overload. The documented renders include the colon form with an error body, `API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}`, bodyless variants such as `503 no healthy upstream`, and the line that explicitly distinguishes itself from a usage limit, `API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited`.

This path retries on an exponential backoff with jitter, and the wait is cumulative with a cap. Jitter matters more here than in a normal retry loop because concurrent clients that all back off in lockstep will hit the same overloaded server again at the same moment. The cap on cumulative waiting is what stops a long-running background session from retrying indefinitely through a sustained outage.

Before typing anything, the tool also checks whether claude is still the foreground process. The design assumption throughout is that the pane may have changed state while it slept, and a stale retry typed into the wrong program is the failure mode the checks exist to prevent.

## Safeguard retries are capped so a real block cannot loop

The third failure mode is an AUP safeguard flag, which the project describes as often transient and frequently a false positive. The tool auto-continues past one, but only for a few tries. The cap is the design point: without it, a safeguard decision that is genuinely correct, meaning your session really is restricted, would be retried forever on a loop that the user never sees and cannot interrupt.

There is a fourth path for a different kind of stall. If a laptop suspends or a connection drops in the middle of a turn, the response is truncated and the session is left parked at an idle prompt with nothing printed. The tool treats that as a recoverable state and picks the work back up, distinct again from the limit case because no reset time was ever printed.

And a fifth covers the near miss. When Claude Code winds a turn down at roughly 95 percent of the five-hour window, printing a line about approaching the usage limit and that it will wrap up the current step, the session parks at an idle prompt with no limit banner present. A monitor that only matches limit text sees nothing to do. This one sends a single continue so the work runs on to the real limit, where the ordinary usage wait takes over. Sending one, rather than several, is what keeps it from looping at the wrap-up point.

## reconcile re-arms monitors that lost one, and a user timer can run it

A monitor living inside a tmux pane is itself a process that can be killed. If it dies, the session is left running inside tmux with nothing watching it, and the next limit hits with no automation at all. The tool covers this with a reconcile command that re-arms monitors for any live claude session that is missing one, and by default you run it yourself. The optional path is a timer: a systemd user unit on Linux, a launchd job on macOS, which runs the same reconciliation automatically.

The repository ships the unit files rather than asking you to write them, and they are visible at the top level under systemd/ and launchd/. That matches the rest of the packaging, which is unusually self-contained: package.json declares two binaries, the main CLI at bin/cli.js and a tmux status script at bin/tmux-status.sh, and the files array includes bin/, src/, systemd/, launchd/, LICENSE, README.md, CHANGELOG.md, and llms.txt. The dependency list is empty and the project requires Node 18 or newer, with the test suite run as `node --test test/*.test.js`.

The status binary is what the tmux status bar indicator reads. It distinguishes a pane that is being monitored, one waiting on a reset, one backing off from overload, and one that has given up, so the state of a long job is visible without attaching to the session and reading logs.

## The Desktop app already has the checkbox, and the CLI gap is the whole premise

The project is explicit that it exists because of a specific gap rather than because auto-continue is a hard problem. As of August 2026, the Claude Desktop app ships a native checkbox for auto-continue when limits reset, so on that client the wait-and-retry already happens without this tool. The CLI does not have the equivalent, and the project points at the upstream issue tracking the native CLI version so that when it lands, this stops being necessary. The npm install line is presented as the way to cover the gap until then.

That framing has a practical consequence for anyone reading the documentation now. Every string the tool matches is a string a future Claude Code release could change. The pattern set is configurable, and the wait margin, retry count, and retry message are configurable too, so a version that renames a banner is a configuration problem rather than a code fork. Bad configuration values fall back to safe defaults instead of crashing, which matters for a tool whose failure mode is sitting in a background loop while you are asleep.

One more mode is worth separating out. The `--print` mode, used for piped and scripted runs, buffers output and retries cleanly rather than driving an interactive pane, so the tmux and send-keys machinery does not apply there. The tables of recognised error renders in the README are cut off partway through the overload section, so the complete pattern list, the exact status bar colours, and the reconcile invocation syntax are not visible in the published page and have to be read from the source or from llms.txt.

## Conclusion

This is for people running long Claude Code sessions unattended, overnight jobs, or anything where a session parked at an idle prompt costs real time. It is not needed if you use the Claude Desktop app, which now has a native auto-continue checkbox, and it will not help on a machine where you cannot install tmux. Before you install, check three things: that the printed reset string your Claude Code version emits actually matches one of the patterns, since the tables stop partway through the README as published; that you understand the monitor injects the literal word continue into a live pane, so a session that has moved on could receive a stray keystroke; and that your version is 0.7.3, since the last push to the repository was 2026-08-26 and several of the recovery paths described here arrived in the 0.7.x line.

## FAQ

### How does claude-auto-retry know when to resume my Claude Code session?

A background monitor polls the tmux pane every five seconds, looks for limit text, and parses the reset clock time printed inside the message rather than computing its own deadline. It waits until that time plus a safety margin, checks that claude is still the foreground process, and then sends continue.

### Does claude-auto-retry need tmux installed on my machine?

It uses tmux so the session survives a dropped connection, a closed terminal, or a suspended laptop, and it installs tmux for you when it is missing using apt, dnf, brew, pacman, or apk. If you are already inside tmux it starts a monitor alongside your existing session instead of creating a new one.

### What happens when claude-auto-retry sees a 529 or a 503 instead of a usage limit?

That takes a separate path from the usage reset. API overload and the 5xx family are retried on an exponential backoff with jitter and a cumulative wait cap, rather than waiting for a printed reset time, so a busy server does not cost you hours of sleep.

### Can claude-auto-retry accidentally type into the wrong program?

Before injecting anything it verifies that claude is still the foreground process in the pane. For the rate limit options menu it locates the stop and wait entry and refuses to press Enter at all if the layout cannot be read, and the safeguard retry path is capped at a few tries so a genuine block cannot loop.

### Is claude-auto-retry still needed on the Claude Desktop app?

The project says the Desktop app now has a native auto-continue when limits reset checkbox, so the gap it covers is on the command line. It points at the upstream Claude Code issue for the native CLI version and presents the npm install as the interim route.

## Sources

- [cheapestinference/claude-auto-retry on GitHub](https://github.com/cheapestinference/claude-auto-retry)
- [Issues](https://github.com/cheapestinference/claude-auto-retry/issues)
- [License: MIT](https://github.com/cheapestinference/claude-auto-retry/blob/master/LICENSE)
- [README](https://github.com/cheapestinference/claude-auto-retry/blob/master/README.md)
- [Releases](https://github.com/cheapestinference/claude-auto-retry/releases)

---

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