`README.md`

61 lines
# claude-auto-resume

Hands-free recovery from Claude Code's transient **"Server is temporarily limiting
requests · Rate limited"** API error (the server-side limiter, *not* your usage cap).
Watches a tmux pane; when the limiter error appears it waits a few seconds and types
`RESUME` + Enter into that pane.

Built 2026-05-30.

## Files

| File | Live location | What it is |
|------|---------------|------------|
| `claude-auto-resume.sh` | `~/bin/` | Per-session foreground watcher. Run on demand in a **separate** pane. Supports `--idle` (also resume when the pane sits unchanged, e.g. Claude stopped at a question). |
| `claude-resume-daemon.sh` | `~/bin/` | Always-on supervisor. Scans **every** tmux pane; resumes any that show the limiter. Run via launchd. |
| `com.steve.claude-auto-resume.plist` | `~/Library/LaunchAgents/` | launchd unit for the daemon. |

> **This repo is the versioned source.** The live copies above are what actually run.
> After editing here, copy back to `~/bin` / `~/Library/LaunchAgents` (or vice-versa) —
> there is no auto-sync.

## Per-session watcher (no launchd)

```sh
# rate-limiter only, exits on recovery:
nohup ~/bin/claude-auto-resume.sh >/tmp/claude-resume.log 2>&1 & disown
# also resume on idle (Claude waiting at a question):
nohup ~/bin/claude-auto-resume.sh --idle >/tmp/claude-resume.log 2>&1 & disown
```
Run it in a **different** pane than the one running `claude` — it drives that pane
via `tmux send-keys`.

## Always-on daemon (launchd)

```sh
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.steve.claude-auto-resume.plist
launchctl print gui/$(id -u)/com.steve.claude-auto-resume | grep -E 'state|pid'
tail -f ~/Library/Logs/claude-auto-resume.log
```
Kill-switch (no unload needed):
```sh
touch ~/.claude-resume-disabled    # pause
rm ~/.claude-resume-disabled       # resume
```
Uninstall: `launchctl bootout gui/$(id -u)/com.steve.claude-auto-resume`

## Tunables (env, set in the plist)

`RESUME_DELAY` (3s) · `RESUME_COOLDOWN` (per-pane, 25–30s) · `RESUME_POLL` ·
`RESUME_TAIL` (bottom-most screen lines scanned) · `RESUME_MSG` (default `RESUME`).

## Design notes

- The TUI **hard-wraps** the error mid-word, so the daemon matches against a
  whitespace-stripped, lowercased capture (`temporarilylimitingrequests|…`) — a
  naive regex with spaces never matches.
- Per-pane cooldown via a state file in `$TMPDIR/claude-resume/` stops it spamming
  while a retry is in flight.
- The daemon never exits on transient tmux errors (no tmux server yet → idle + retry),
  so launchd doesn't crash-loop.