claude-auto-retry solves one narrow annoyance: Claude Code stops when you hit a subscription usage limit, and nothing resumes it until you come back and type continue. For a task running overnight, that means the machine sat idle for hours. The tool waits for the reset and sends the continuation itself. Its README sums up the intent as “No dependencies. No workflow change. Just install and forget.”
It is MIT licensed and installs from npm.
Read this before you install it
The README carries an August 2026 status note: the Claude Desktop app now has a native auto-continue checkbox, while the CLI does not, and the project tracks that gap in anthropics/claude-code#35744.
That reframes the tool. It is no longer a general convenience — it is a stopgap for the terminal, and its useful life is tied to an upstream feature request. If you work in the desktop app, use the built-in checkbox. If you drive Claude Code from a terminal, especially over SSH on a remote box, the gap is real and this fills it.
How it actually works
The mechanism is worth knowing, because it explains both the requirements and the failure modes:
- A shell function is injected into
.bashrcor.zshrcand runsclaudeinside a tmux session, creating one if you are not already in tmux. - A background monitor polls the tmux pane every five seconds looking for the rate-limit text.
- It parses the reset time — the README notes timezone and DST handling — and waits until reset plus a safety margin, 60 seconds by default.
- It confirms Claude is still the foreground process, then sends
continuewithtmux send-keys.
Because the session lives in tmux, the monitor survives a dropped SSH connection or a sleeping laptop. That is the actual reason to use it rather than a shell loop of your own.
The README also recommends a better detection path than screen scraping: an optional StopFailure hook, which is event-driven rather than pattern-matched. If you install this, use the hook.
Installing
npm i -g claude-auto-retry
claude-auto-retry installThen run claude as usual. Other subcommands include status, logs, reconcile, install-hook, install-timer and uninstall. Requirements are Node.js 18 or later and tmux 2.1 or later, with tmux auto-installed via apt, dnf, brew, pacman or apk if missing.
Configuration is optional, in ~/.claude-auto-retry.json. The documented defaults are five retries, a five-second poll interval, a 60-second margin, a five-hour fallback wait, and a retry message of “Continue where you left off. The previous attempt was rate limited.” Invalid values “fall back to defaults automatically.”
Beyond the rate-limit case the README documents several other recovery paths: exponential backoff with jitter for sustained 429/5xx/529 errors capped at 120 cumulative minutes, up to three retries for false-positive safeguard flags, two attempts to resume an interrupted stream, a single wrap-up nudge at about 95% of the window, and a tmux status-bar indicator showing the current state.
Where it will bite you
The README is commendably honest about its own limits, and these are worth repeating:
- Windows is “Not supported natively” — WSL2 is the recommended route. bash and zsh are fully supported; fish needs manual setup.
- The Node path is fixed at install time. Switch Node versions with nvm and you must re-run
install. - Screen scraping has false positives. The README notes that overload detection can match a live terminal containing
API Error: 529— for instance while you are editing the tool itself — and suggests disabling it in that case. - The retry message is plain text. If Claude is sitting in a special input state, it may not be read as a continuation.
- tmux is mandatory, and installing it may need sudo.
A utility that tells you when to stop needing it
A well-scoped utility with an unusually candid README, and the candour extends to telling you that the desktop app has since solved this natively. For terminal and remote workflows it still earns its install; for desktop users it has been overtaken. Either way, prefer the StopFailure hook over terminal pattern matching, and expect to re-run install after a Node version change.
