DOCSEARCHbyAlgolia
Submit Docs

claude-auto-retry

repository·master·Indexed 42 days ago

https://github.com/cheapestinference/claude-auto-retry

A tool to automatically resume Claude Code CLI sessions when encountering Anthropic subscription rate limits or transient API errors (529/500/503). Version 0.7.3 uses tmux to persist sessions and provides exponential backoff for API overloads, safeguard nudge retries, and interrupted-stream resumption. It includes a shell wrapper, a StopFailure hook for event-driven detection, and a tmux status bar indicator to monitor session states.

Tokens
20.1K
Snippets
71
Records
93
Agent score
57%

What's inside claude-auto-retry

  1. Maintain monitor coverage with reconcile and timers

    master

    Monitors are detached processes. If a monitor is killed or a claude session is started outside the wrapper, that session will be unmonitored. Use these tools to ensure continuous coverage:

    1. reconcile: Scans live tmux panes for claude processes and arms a monitor for any that are not currently covered. This is idempotent and safe to run repeatedly.
    2. install-timer: Automates coverage by running reconcile every 5 minutes using system-native tools (systemd --user on Linux or launchd on macOS).

    To exclude a specific session from being monitored (e.g., when manually handling rate limits), run claude-auto-retry exclude-self from within that session. This uses a self-expiring PID-based mechanism.

  2. How the StopFailure hook and daemon work together

    master

    The most reliable way to handle API errors in claude-auto-retry is by pairing the Claude Code StopFailure hook with the claude-auto-retry daemon. This architecture eliminates the need for terminal scraping.

    1. The Hook (StopFailure): Acts as the detector. It is an observability-only mechanism that fires when a turn ends due to an API error. It cannot act (it cannot inject prompts or run commands), but it can write a marker file to ~/.claude-auto-retry/events/ containing the error type, session ID, and transcript path.
    2. The Daemon: Acts as the actuator. It watches for these marker files, maps the session/pane, applies backoff logic, and uses tmux send-keys to trigger the retry.

    This method is superior to scraping because it uses the structured error_type provided by the Claude Code binary, avoiding false positives from human-readable text in the terminal.

    // Conceptual flow of the StopFailure architecture
// Hook (Detector) -> Writes Marker -> Daemon (Actuator) -> tmux send-keys

// The hook payload provided by Claude Code:
// hookInput = {
//   hook_event_name: "StopFailure",
//   error, // The type string (e.g., 'overloaded', 'server_error')
//   error_details,
//   last_assistant_message
// }

  3. Use the JSONL-tail fallback for error detection

    master

    If you cannot or do not want to install the StopFailure hook, claude-auto-retry can fall back to monitoring the Claude Code session transcript.

    Claude Code writes append-only JSONL files at: $CLAUDE_CONFIG_DIR/projects/<cwd-slug>/<sessionId>.jsonl

    The tool detects a retryable error by looking for the last record in the JSONL file where:

    • type is "assistant"
    • isApiErrorMessage is true

    Warning: Do not attempt to implement your own detection by grepping the message body for strings like overloaded_error, as these can appear in normal conversation content and cause false positives.

  4. How claude-auto-retry works with tmux

    master

    The tool uses tmux to ensure sessions persist even if your terminal disconnects (e.g., SSH drops, laptop sleeps).

    • If you are already in a tmux session: It starts a background monitor and launches Claude with the full TUI.
    • If you are NOT in tmux: It transparently creates a new tmux session, launches Claude + the monitor inside it, and attaches you to it. It will even auto-install tmux via your system package manager (apt, dnf, brew, etc.) if it is missing.

    When a rate limit is detected, the background monitor waits for the reset time (plus a safety margin) and then sends the continue command via tmux send-keys.

  6. Run tests for claude-auto-retry

    master

    The project uses npm test and Node's built-in test runner. You can run the full suite, a specific file, or use watch mode.

    npm test                              # Run all tests
node --test test/patterns.test.js     # Run a single test file
node --test --watch test/             # Run tests in watch mode
    npm test                              # All tests
node --test test/patterns.test.js     # Single file
node --test --watch test/             # Watch mode

  7. Install and setup claude-auto-retry

    master

    To use claude-auto-retry to automatically resume Claude Code sessions when rate limits are hit, install the package globally and run the install command. This injects a shell function into your .bashrc or .zshrc so that typing claude uses the auto-retry wrapper instead of the raw CLI.

    Note: As of August 2026, the Claude Desktop app has native auto-continue support, but the Claude CLI still requires this tool.

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

  8. Install the StopFailure hook for event-driven detection

    master

    Instead of relying on terminal scraping (heuristics), you can install the StopFailure hook. This is the recommended method as it uses an exact, ambiguity-free trigger provided by Claude Code when a turn ends in an API error.

    Once installed, sessions launched via the wrapper will automatically use event mode, which disables the scraper and prevents false positives on code or scrollback.

    Commands:

    • Install to default config directory: claude-auto-retry install-hook
    • Install to a specific path: claude-auto-retry install-hook /path/to/config
    • Remove the hook: uninstall-hook
    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

  9. Install the StopFailure hook

    master

    To enable the highest-leverage error detection (replacing the heuristic scraper), you can install the StopFailure hook. This allows the tool to react to structured error events rather than scraping the terminal output.

    Use the install-hook command to register the hook with Claude Code. This will install the claude-auto-retry _stopfailure-hook into your Claude configuration (e.g., in settings.json under hooks.StopFailure).

    install-hook

  10. Frequently Asked Questions about claude-auto-retry

    master

    Subscription Compatibility

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

    Environment & Usage

    Does it work outside of tmux? Yes. If you are not currently in a tmux session, the tool will create one transparently.

    What if I continue manually before the retry fires? The monitor checks if the rate limit message is still visible on the screen before sending keystrokes. If you have already manually continued, the monitor resets and continues watching.

    What if Claude exits while the monitor is waiting? The monitor checks the Claude process status every 30 seconds during the wait period. If the process has exited, the monitor shuts down cleanly.

    Performance & Safety

    Does it consume a lot of resources? No. The monitor uses tmux capture-pane, which is extremely lightweight. It typically uses ~0% CPU with a 5-second polling interval.

    Can it accidentally type into the wrong program? No. The monitor verifies that the foreground process is either node or claude before injecting any keystrokes. If you switch to another program (like vim or bash), it will skip the retry.

  11. Install the self-healing reconcile timer

    master

    To ensure that Claude sessions are always monitored (even after a crash or system reboot), install a background timer that runs the reconcile command every 5 minutes.

    • Linux: Installs a systemd --user service and timer.
    • macOS: Installs a launchd LaunchAgent in ~/Library/LaunchAgents.

    Note: The timer pins the current Node path. If you switch Node versions (e.g., via nvm), you must re-run this command.

    claude-auto-retry install-timer

  12. Add a tmux status bar indicator

    master

    You can monitor the state of your Claude sessions directly in your tmux status bar. To do this, add a segment to status-right or status-left in your ~/.tmux.conf that calls the bundled tmux-status.sh script.

    Important: You must use an absolute path to the script. Because tmux commands run in the tmux server's environment, they may not have access to your shell's PATH (e.g., if you use nvm). Use which claude-auto-retry-tmux-status in a normal shell to find the correct path.

    Pass both the current pane ID (#{pane_id}) and the server's socket path (#{socket_path}) to ensure the indicator works correctly if you run multiple tmux servers.

    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"