agent-autoresume

Stop babysitting AI coding-agent usage limits. When Claude Code or Codex hits your 5-hour / weekly limit it just stops and waits for you to resubmit. These small, dependency-free tools wait out the limit and resume the work for you.

Unofficial. Not affiliated with Anthropic or OpenAI.

Which one?

Tool	When	Setup
iTerm2 watcher	You use iTerm2	install once → runs forever
tmux watcher	Any terminal (Terminal.app, Ghostty…)	install once → runs forever
headless wrapper	Unattended one-shot / overnight jobs	run a command

The two watchers are set-and-forget: install once, they auto-start at login and resume your sessions whenever a limit lifts. You keep running claude / codex exactly as normal. Both support Claude Code and Codex.

Install

iTerm2:

curl -fsSL https://raw.githubusercontent.com/StylesDevelopments/agent-autoresume/main/iterm/install-iterm.sh | bash

Then enable iTerm2 → Settings → General → Magic → Enable Python API and start it once from Scripts → AutoLaunch (it auto-starts every launch after that).

Terminal.app / any terminal (tmux):

curl -fsSL https://raw.githubusercontent.com/StylesDevelopments/agent-autoresume/main/tmux/install-tmux.sh | bash

Installs a launchd login agent that runs forever. Just run your agents inside tmux. Needs tmux + python3.

Don't want to remember to start tmux first? Add AUTORESUME_WRAP=1 (or pass --wrap) to also install a small opt-in zsh shim, so plain claude / codex auto-launch inside tmux in any terminal:

curl -fsSL https://raw.githubusercontent.com/StylesDevelopments/agent-autoresume/main/tmux/install-tmux.sh | AUTORESUME_WRAP=1 bash

The shim passes through unwrapped for non-interactive runs (-p, --version, exec, piped output) and can be skipped per-invocation with AUTORESUME_NO_WRAP=1. Remove it by deleting the source …/shell-wrap.zsh line from your ~/.zshrc.

Headless wrapper (unattended jobs):

curl -fsSL https://raw.githubusercontent.com/StylesDevelopments/agent-autoresume/main/install.sh | bash
agent-autoresume "big task"            # Claude Code
agent-autoresume --codex "big task"    # Codex

How it works

A watcher reads your terminal screen, spots a blocking limit banner (You've hit your … limit · resets 3:45pm, … resets in 1d 5h, or Codex … try again at 3:45 PM), waits until the reset, then types a clear marker — ** USAGE LIMIT RESET, RESUME SESSION ** — back into that session. If Claude shows its interactive limit menu, the watcher selects the highlighted Stop and wait for limit to reset option. The iTerm2 watcher uses iTerm2's API; the tmux watcher uses capture-pane/send-keys — neither needs macOS Accessibility/screen-recording permission.

Claude Code statuslines can also show a non-blocking quota footer such as Usage ⚠ Limit reached (resets in 1d 5h) while requests still work. The watchers intentionally ignore that footer by itself and wait for an actual blocked-turn banner before resuming.

Tune via env vars (see each script's header or --help). Test safely first with AUTORESUME_DRY_RUN=1 (logs what it would do, sends nothing).

Caveat: it's screen-scraping, so it depends on the banner wording — if a tool changes it, that's a one-line regex tweak in limit_detect.py (covered by tests + CI).

Develop

python3 tests/test_limit_detect.py        # detection + reset-time parsing
python3 iterm/test_limit_watcher.py       # iTerm soft-wrap + import wiring
bash    tests/test_tmux_integration.sh    # end-to-end: real tmux pane, real resume
bash    tests/test_shell_wrap.sh          # opt-in zsh shim: passthrough + quoting (needs zsh)

CI runs all of the above (plus bash -n, py_compile, shellcheck) on every push and PR.

License

MIT — see LICENSE.