render, so a bare 503 in code you're editing (res.status(503)), a

port number, a quoted log, or a status.claude.com link in a comment will not

trip detection. The one residual: a live tail that literally contains

API Error: 529 (e.g. editing this tool, or docs about Claude errors) will match —

set "enabled": false while doing that. (Earlier versions matched bare status

numbers across the whole capture, which injected spurious retries during ordinary

web-dev sessions.) For a structured, ambiguity-free trigger see DESIGN-NOTES.md.

Configured under an overload block (shown with its defaults):

{
  "overload": {
    "enabled": true,
    "patterns": ["API Error:\\s*(429|500|502|503|504|529)\\b", "overloaded_error", "temporarily limiting requests"],
    "backoffSeconds": [30, 60, 120, 240, 300],
    "steadyStateSeconds": 300,
    "jitterPct": 15,
    "maxTotalWaitMinutes": 120,
    "retryMessage": "Continue where you left off.",
    "relaunchOnExit": false,
    "relaunchCommand": "claude --continue"
  }
}

| Option | Default | Description | |--------|---------|-------------| | enabled | true | Turn the overload path on/off | | patterns | (see above) | Case-insensitive regexes matching a terminal overload error in the pane tail (last 12 lines) | | backoffSeconds | [30,60,120,240,300] | Wait before each retry; index i for attempt i | | steadyStateSeconds | 300 | Wait once the backoffSeconds array is exhausted | | jitterPct | 15 | ±% jitter applied to every wait (clamped 0–100) | | maxTotalWaitMinutes | 120 | Cumulative-wait cap — give up loudly past this | | retryMessage | "Continue where you left off." | Sent to Claude on each retry | | relaunchOnExit | false | See the gating decision below | | relaunchCommand | "claude --continue" | Command used by relaunchOnExit |

The waits go 30 → 60 → 120 → 240 → 300 → 300 …, each with ±15% jitter, until the error clears (success) or the cumulative wait reaches maxTotalWaitMinutes (give up — the cap guards against hammering a genuinely-down endpoint or masking a real outage; check status.claude.com).

Event-driven detection (recommended — no scraping)

The scraper above is a heuristic over terminal output. For an exact, ambiguity-free trigger, install the StopFailure hook — Claude Code fires it precisely when a turn ends in an API error, with a typed error class:

claude-auto-retry install-hook                  # into $CLAUDE_CONFIG_DIR or ~/.claude
claude-auto-retry install-hook /path/to/config  # repeat per CLAUDE_CONFIG_DIR you use

This adds a StopFailure hook (matcher overloaded|server_error) that writes a pane-keyed marker the monitor consumes — no terminal scraping, so it cannot false-positive on code or scrollback. Sessions launched via the wrapper after installing the hook use it automatically; the first marker latches event mode and disables the scraper for that session. Sessions without the hook (or pre-install) fall back to the anchored scraper. Remove with uninstall-hook. See DESIGN-NOTES.md for the architecture.

Why not rate_limit? The event path handles only transient overloads

(seconds-scale backoff). A rate_limit is the subscription session/usage limit —

an hours-scale wait until a printed reset time — so it's handled by the usage-wait

path above, not the overload path. Routing it through the hook would fire premature

retries against a session that's simply out of quota.

Gating decision (alive-at-prompt vs exited-to-shell)

A transient API error in interactive Claude Code surfaces inline and leaves the process alive at its prompt — it does not exit to the shell. So the default, robust behavior reuses the existing usage-limit mechanism: only retry when the foreground process is claude/node and the session is idle, not working (the esc to interrupt footer is absent). Retrying mid-internal-retry would double-drive the session, so that case is deferred, never sent.

If a 500 ever does drop you to the shell, send-keys is correctly blocked by the foreground check (it never types into bash), and the tool logs overload-exited-to-shell rather than masking it. Auto-relaunch is **off by default** — blindly typing claude --continue into a shell the user may be using is worse than surfacing the stall. Set relaunchOnExit: true (and adjust relaunchCommand) only if you actually observe shell-exits on overload.

Safeguard retry

A third failure mode, separate from usage limits and 5xx overloads: the model's safeguards flag your message and Claude Code can't respond. It renders like:

● API Error: Fable 5's safeguards flagged this message (…/legal/aup). They may flag
  safe, normal content as well. … Claude Code can't respond to this request with Fable 5.
  Double press esc to edit your last message, or try a different model with /model.

These flags are often false positives (the message says so) and semi-random, so an immediate re-send frequently clears them. When the tool sees this render at an idle prompt, it sends a short retry message (continue by default), waits a few seconds, and repeats — but only up to maxRetries times, then gives up loudly (logged) rather than looping. A sticky flag means the content/model combination is genuinely blocked; switch models with /model or rephrase.

Detection is tail-anchored (last 12 pane lines) like the overload path, and a match additionally requires the API Error render line nearby — so the phrases appearing in scrollback or in a conversation about safeguards won't trigger it.

Configured under a safeguard block (defaults shown):

{
  "safeguard": {
    "enabled": true,
    "patterns": ["safeguards flagged this message", "can't respond to this request with", "legal/aup"],
    "maxRetries": 3,
    "retryDelaySeconds": 8,
    "retryMessage": "continue"
  }
}

| Option | Default | Description | |--------|---------|-------------| | enabled | true | Turn the safeguard-retry path on/off | | patterns | (see above) | Case-insensitive regexes marking the safeguard render (matched in the pane tail, near an API Error line) | | maxRetries | 3 | Re-send attempts before giving up — kept small; retrying a sticky flag won't help | | retryDelaySeconds | 8 | Wait between re-sends | | retryMessage | "continue" | Message sent to nudge past the flag |

Usage limits always take precedence; the safeguard path only acts when Claude is idle (no esc to interrupt footer) and the foreground process is claude/node.

Interrupted-stream resume

Close your laptop lid while Claude is mid-answer and the work does not survive. Claude Code wraps the response body in a byte watchdog; when the bytes stop arriving it aborts the stream and finalizes whatever had already been printed, naming the cause:

⏺ API Error: Your computer went to sleep mid-response. The response above may be
  incomplete.

The turn is then over. The prompt returns idle and nothing resumes it, so the session sits there — potentially for hours — with a half-finished answer on screen. Claude Code retries by itself only while the response is still thinking-only; once real content has been yielded it declines to retry, which is exactly when this render appears. That is the gap this closes: seeing it at an idle prompt, the tool sends continue, bounded at maxRetries because a machine that just woke may not have its network back yet.

The same finalizer emits the render for a dropped connection, a stalled stream and a mid-response server error. All are the same truncated-turn state with the same remedy, so all are matched — sleeping is just the cause we can name.

Detection is anchored on the shape of the line, not its vocabulary: a real render begins with API Error:, behind at most Claude's message glyph. The "an API Error line nearby" rule the overload and safeguard paths use is deliberately not enough here — these sentences are ordinary English, so a session merely explaining them quotes the whole render, anchor included, mid-sentence. Prose carries it mid-line and your own typed line carries ❯, so neither trips it.

Configured under a streamInterrupted block (defaults shown):

{
  "streamInterrupted": {
    "enabled": true,
    "patterns": ["went to sleep mid-response", "Connection lost mid-response", "…"],
    "maxRetries": 2,
    "retryDelaySeconds": 5,
    "retryMessage": "continue"
  }
}

| Option | Default | Description | |--------|---------|-------------| | enabled | true | Turn the interrupted-stream path on/off | | patterns | (all 7 renders) | Case-insensitive regexes, matched only against a line that begins with the API Error: render | | maxRetries | 2 | Resume attempts before giving up loudly | | retryDelaySeconds | 5 | Wait before resuming — lets the network settle after a wake | | retryMessage | "continue" | Message sent to pick the work back up |

Usage limits take precedence, and like the safeguard path this only acts when Claude is idle and the foreground process is claude/node.

Near-limit wrap-up nudge

At roughly 95% of the 5-hour window, Claude Code injects a checkpoint instruction into the model's context — *finish the current step, then list up to three short bullets of the most impactful remaining work, don't start subagents or long-running work* — and prints:

⏺ Approaching your 5-hour usage limit — Claude will wrap up the current step.

The model does exactly that and ends the turn. There is no limit banner (the limit has not been hit), the prompt returns idle, and nothing resumes the session — so an overnight run winds down at 95% and stays parked long after the window has reset. This is a server-side Claude Code behavior with no user-facing switch (it is feature-flagged, not a setting), so the tool handles the render instead.

Seeing the notice at an idle prompt, the tool sends one continue. The session then either finishes its work or runs into the real limit, where the usage wait takes over as usual. Unlike the retry families above this is not a bounded machine: the nudge renders as a user row under the notice, and a notice with a user row below it — yours or ours — belongs to a turn that has already been answered, so it is never nudged twice. The maxRetries cap only bounds the pathological case where the nudge never renders.

Detection is anchored on the shape of the line, like the interrupted-stream render: the notice begins its line, behind at most Claude's message glyph, so prose quoting it and your own typed copy don't trip it.

Configured under a nearLimitWrapUp block (defaults shown):

{
  "nearLimitWrapUp": {
    "enabled": true,
    "maxRetries": 3,
    "retryMessage": "continue"
  }
}

Set "enabled": false if you want the session to stop at the checkpoint.

Native stale-reset nudge

Claude Code v2.1.234+ waits out a usage limit itself and continues at the reset. But if the machine slept more than ~30 minutes past the reset, it does not continue on wake. Its two status lines change to:

Your usage limit has reset
Press enter to continue

and the session waits for a human Enter — indefinitely. The limit banner is gone by then, so the tool's own wait (which usually armed on the same banner and slept along with the host) used to read that screen as "you already continued" and stand down, leaving the session parked. Now the wait's recheck recognizes the pair and hands it to this nudge: at an idle prompt, with claude/node in the foreground, the tool presses a bare Enter (the key the UI asks for — no message is typed). If the pair clears, the episode is over; if it is still there after maxRetries presses, the tool gives up loudly (🔴AR) rather than keep pressing. Once the pair is gone, even after a give-up (say you pressed Enter yourself and the session is working), the tool goes back to normal monitoring and 🔴AR clears. A live usage-limit banner always takes precedence.

Detection is anchored on where the pair sits, not just its words. The real stale rows are status chrome: they are the bottom-most content of the pane, below the input box. So the pair only matches when Press enter to continue is the last content row (UI footer aside), Your usage limit has reset is the nearest non-blank row above it, and both sit below the input row (❯, empty or holding a draft) when one is on screen. Model output always renders above the input box. A reply or code block quoting the pair, even on indented lines of its own, therefore doesn't match. Each phrase must also begin its line (behind at most indentation and one chrome marker such as │ or ⎿). That rules out mid-sentence quotes, the model's ⏺ output and your own ❯ row, and tool-call output is excluded as well. Press enter to continue on its own is a generic phrase and never matches.

Configured under a nativeStaleReset block (defaults shown):

{
  "nativeStaleReset": {
    "enabled": true,
    "maxRetries": 2,
    "retryDelaySeconds": 3
  }
}

| Option | Default | Description | |--------|---------|-------------| | enabled | true | Turn the stale-reset nudge on/off | | maxRetries | 2 | Enter presses before giving up loudly | | retryDelaySeconds | 3 | Wait before each press — lets the wake and native's redraw settle |

The status bar shows 🟢AR while the nudge is in progress (it lasts seconds) and 🔴AR if it gave up, until the session is working again.

tmux status bar indicator

The monitor writes a small JSON snapshot per pane on every poll tick, so you can tell at a glance — without checking logs — whether a pane is being watched, waiting out a usage-limit reset, backing off from overload or a safeguard flag, or has given up.

Add a segment to status-right (or status-left) in ~/.tmux.conf that shells out to the bundled reader script, passing the current pane id and the server's socket path:

set -g status-interval 5
set -g status-right "#(~/.local/lib/node_modules/claude-auto-retry/bin/tmux-status.sh '#{pane_id}' '#{socket_path}') | %Y-%m-%d %H:%M"

Use an absolute path, not the bare command name. #() commands run inside the tmux server's own environment, not the environment of whichever shell you attached from — if the server was started before your shell rc added npm/nvm's bin directory to PATH (e.g. tmux auto-started at login, or by another program), the bare command name resolves to nothing and the segment stays permanently blank with no error anywhere. Find your actual install path with which claude-auto-retry-tmux-status (run it in a normal shell, then hardcode that path in .tmux.conf) if it differs from the example above. If you use nvm and switch Node versions, re-check the path.

tmux substitutes #{pane_id} and #{socket_path} itself before running the command (these are tmux format variables, resolved at expansion time — not environment variables the script has to go looking for), so the segment always reflects whichever pane you're looking at, correctly scoped to the tmux server it belongs to. The socket_path argument matters if you ever run more than one tmux server on the same machine (e.g. tmux -L work, tmux -L personal, or two users' default servers on a shared host): pane ids like %2 are only unique within a server, so without it two different servers' %2 panes would render each other's status. Always pass it: the monitor keys each status file by the socket path it inherits from $TMUX, so a single-argument config looks under a shared default key the monitor never writes to, and the segment simply stays blank.

It prints:

| Pane state | Indicator | |------------|-----------| | Actively monitoring | 🟢AR | | Waiting on a usage-limit reset | ⏳AR 1h30m | | Backing off from overload | 🟠AR 45s | | Retrying past a safeguard/AUP false-positive | 🛡AR 8s | | Given up — max retries/backoff cap reached; no further automatic action on this pane | 🔴AR | | No monitor for this pane, or the status file is stale (monitor process died without cleaning up) | (nothing) |

🔴AR overrides whatever the underlying status would otherwise render. Several give-up paths intentionally leave the monitor's internal status at whatever it was when it stopped acting (so the scraper/event logic doesn't re-detect its own stale error next tick) — without an explicit gaveUp flag in the snapshot, the status bar would keep showing a live 🟢/⏳/🟠 indicator for a monitor that will not act again on this pane until the underlying condition clears on its own.

Staleness is derived from each snapshot's own pollIntervalSeconds (age > 2× the monitor's configured poll interval) rather than a fixed constant, so a healthy monitor running with a longer pollIntervalSeconds doesn't have its segment blank out for a large fraction of every tick.

The script (bin/tmux-status.sh) is pure POSIX shell with no dependencies (no jq, no node), so it's cheap to run every few seconds from every attached client. status-interval defaults to 15s in tmux; dropping it to 5 (matching the monitor's default pollIntervalSeconds) keeps the overload countdown responsive.

CLI Commands

claude-auto-retry install          # Install shell wrapper + tmux
claude-auto-retry uninstall        # Remove shell wrapper
claude-auto-retry status           # Show monitor activity + last log entries
claude-auto-retry logs             # Tail today's log file in real-time
claude-auto-retry version          # Print version
Event-driven overload detection (optional; see "Overload backoff")
claude-auto-retry install-hook [dir]    # Install the StopFailure hook into a config dir
claude-auto-retry uninstall-hook [dir]  # Remove it
Monitor coverage (see "Keeping monitors alive")
claude-auto-retry reconcile        # Re-arm a monitor for every live claude pane not covered
claude-auto-retry reconcile --dry-run   # Preview without arming
claude-auto-retry install-timer    # Run reconcile every 5 min (systemd --user on Linux,
                                   # launchd LaunchAgent on macOS)
claude-auto-retry uninstall-timer  # Remove the timer
claude-auto-retry exclude-self     # Keep THIS session unmonitored (durable, self-expiring)

For AI Agents

If you are an AI agent (Claude Code, Codex, etc.) installing this for your user, the full setup is non-interactive:

npm install -g claude-auto-retry
claude-auto-retry install        # shell wrapper (+ tmux if missing)
claude-auto-retry install-hook   # recommended: event-driven, scrape-free overload detection

Notes for agents:

• The wrapper takes effect in new shells — have the user source their shell rc or

• Verify with claude-auto-retry status (monitor activity) and claude-auto-retry logs.
• Configuration is optional and defaults are safe. To change it, write

• If the user runs multiple CLAUDE_CONFIG_DIRs, repeat claude-auto-retry install-hook per dir.
• Clean removal: claude-auto-retry uninstall and claude-auto-retry uninstall-hook.

Keeping monitors alive

Each claude you launch through the wrapper gets its own background monitor. Monitors are detached processes with no supervising service, so if one is killed — or a claude is started outside the wrapper — that session ends up unmonitored, and only new sessions get a monitor. Two commands restore and maintain full coverage:

• reconcile re-arms a monitor for every live tmux pane running claude that isn't

• install-timer wires reconcile to a timer that runs every 5 minutes, so a

Excluding a session. To keep a specific session unmonitored (e.g. one where you're pasting rate-limit text and don't want any auto-retry), run claude-auto-retry exclude-self from inside it. This records the session's claude PID in ~/.claude-auto-retry/reconcile-exclude; both reconcile and the timer skip it. Keying on the PID makes the entry self-expiring: dead PIDs are pruned when the file is read, so once that claude exits its entry is dropped and can never accidentally mute a later session (tmux reuses pane ids, so a hand-added %pane exclude could — pane ids are not pruned, since staleness can't be detected). Prefer the PID form; you can also hand-add a %pane id or a PID to that file.

Platform Support

Operating Systems

| OS | tmux auto-install | Status | |----|-------------------|--------| | Ubuntu / Debian | apt-get | Fully supported | | CentOS / RHEL / Fedora | dnf | Fully supported | | Rocky Linux / Amazon Linux | dnf | Fully supported | | macOS | brew | Fully supported | | Arch Linux | pacman | Fully supported | | Alpine | apk | Fully supported | | Windows | — | Not supported natively — the tool drives a tmux pane, which Windows does not have. Use WSL2 (Ubuntu), where it works as on Linux. A native backend via a tmux-compatible multiplexer is being discussed in #79. |

Requirements

• Node.js >= 18
• tmux >= 2.1 (auto-installed if missing)

Shell Support

| Shell | Status | |-------|--------| | bash | Full (auto-install to ~/.bashrc) | | zsh | Full (auto-install to ~/.zshrc) | | fish | Manual setup (instructions printed on install) |

--print Mode

For scripted/piped usage (claude -p "..." | jq), the tool:

1. Buffers all output (nothing goes to stdout until done)
2. If rate-limited: discards partial output, waits, re-executes with same args
3. Consumer receives a single clean response

# This just works — retries transparently if rate-limited
claude -p "Generate a JSON schema" | jq .

Logging

Logs are written to ~/.claude-auto-retry/logs/YYYY-MM-DD.log:

[2026-03-18 15:00:05] [INFO] Monitor started for pane %3 (claude PID: 12345)
[2026-03-18 15:32:10] [INFO] Rate limit detected: "5-hour limit reached - resets 3pm". Waiting 3547s...
[2026-03-18 16:01:10] [INFO] Sent retry message (attempt 1)

Logs rotate daily. Files older than 7 days are cleaned automatically.

Uninstall

claude-auto-retry uninstall
npm uninstall -g claude-auto-retry

This removes the shell function from your rc files. tmux is left installed.

Known Limitations

1. Retry message context — The retry message is sent as plain text. If Claude was mid-confirmation or in a special input state, it may not interpret it as a continuation. You can customize the message via config.

1. Node version lock — The launcher path is resolved at install time. If you switch Node versions with nvm, re-run claude-auto-retry install.

1. tmux required — The tool needs tmux to monitor terminal output and inject keystrokes. It auto-installs if missing, but requires sudo for system package managers.

Contributing

Contributions are welcome! Here's how to get started:

Development Setup

git clone https://github.com/cheapestinference/claude-auto-retry.git
cd claude-auto-retry
npm test            # Run all 128 tests
npm link            # Install locally for testing

Project Structure

claude-auto-retry/
├── bin/cli.js              # CLI: install, hook, reconcile, timer, status, logs, ...
├── src/
│   ├── patterns.js         # Rate limit + overload detection + ANSI stripping
│   ├── time-parser.js      # Reset time parsing with timezone support
│   ├── config.js           # Config loading + validation
│   ├── logger.js           # File-based logging with rotation
│   ├── tmux.js             # tmux command wrappers (execFile-based)
│   ├── monitor.js          # Core monitoring loop + retry logic (usage + overload paths)
│   ├── events.js           # StopFailure hook event channel (scrape-free overload trigger)
│   ├── reconcile.js        # Re-arm monitors for all live claude panes + exclusion
│   ├── launcher.js         # Process orchestration + signal forwarding
│   └── wrapper.sh          # Shell function template
├── systemd/                # systemd --user units for the reconcile timer (Linux)
├── launchd/                # LaunchAgent plist for the reconcile timer (macOS)
├── test/                   # tests across the src modules
├── package.json
├── LICENSE
└── README.md

Architecture Decisions

• Zero dependencies — only Node.js built-ins. Reduces supply chain risk and install size.
• execFile over exec — all child process calls use array-based args to prevent shell injection.
• stdio: 'inherit' — Claude gets the real TTY for full TUI support. The monitor reads pane content independently via tmux capture-pane.
• Iterative DST correction — timezone offset is computed via 3-iteration convergence loop, not a single-shot formula that breaks at DST boundaries.
• Config validation — invalid user config values fall back to safe defaults instead of producing NaN/undefined behavior.

Running Tests

npm test                              # All tests
node --test test/patterns.test.js     # Single file
node --test --watch test/             # Watch mode

Submitting Changes

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Write tests first (TDD)
4. Make your changes
5. Ensure all tests pass (npm test)
6. Submit a Pull Request

Areas for Contribution

• New rate limit patterns — If you see a Claude Code rate limit message that isn't detected, open an issue with the exact text.
• Fish shell support — Auto-install for fish shell (currently manual).
• Windows support — WSL works, but native Windows would need a different approach.
• Notification integration — Desktop/Slack notification when rate limit detected or when Claude resumes.

Related Projects

• claude-code-queue — Queue-based task system for Claude Code with rate limit handling
• opencode-claude-quota — Rate limit quota monitoring (display only)

FAQ

Q: Claude Code now continues automatically after a limit reset (v2.1.234+). Is this tool obsolete? A: For the basic interactive case — yes, and the native feature does it better (it gets the reset time from the API instead of parsing the terminal). What remains is everything around that case: surviving disconnects via tmux, waits the native feature won't arm, headless -p runs, and the non-limit failures (overload, safeguards, interrupted streams, wrap-up parking). See Native auto-continue vs this tool for the verified comparison.

Q: Does this work with Claude Max/Pro/Team? A: Yes. It works with any Anthropic subscription that has usage-based rate limits.

Q: Does it work outside of tmux? A: Yes. If you're not in tmux, it creates a tmux session transparently. You won't notice a difference.

Q: What if I continue manually before the retry fires? A: The monitor checks if the rate

... (README truncated for length)