Claude Auto-Resume

A tiny, dependency-free wrapper around the claude CLI that automatically resumes your session when a usage limit resets.

You run it in place of claude. It launches the real claude under a pseudo-terminal and passes everything through transparently. When it notices a usage-limit message with a reset time (or a short "try again in Ns" backoff), it waits until the limit lifts and then types your resume text (default: proceed) straight into the session. That's it — no window scraping, no focus-stealing keystrokes, and it only ever looks at your session's output.

Install

It's a single file, standard library only (Python 3.9+), macOS and Linux.

git clone https://github.com/alnordg/Claude-Auto-Resume.git
# The easiest way to use it is an alias:
alias claude='python3 /path/to/Claude-Auto-Resume/claude_watcher.py'

Use

Just start Claude the way you normally would — any arguments are passed straight through to the real claude:

claude
claude --resume
claude -p "summarise this repo"

When you hit a limit you'll see a line like:

[claude-resume] Usage limit detected (resets 15:15). Sending 'proceed' at 15:15:30 (in 42m).

…and at that time it resumes for you. If the limit is somehow still in effect, the detector stays armed and simply reschedules.

Options

All optional. Pass as leading flags, or set the environment variable.

Flag	Env var	Default	Meaning
--resume-text TEXT	CLAUDE_RESUME_TEXT	proceed	What to type on resume
--resume-buffer N	CLAUDE_RESUME_BUFFER	30	Extra seconds to wait past the reset time
--resume-dry-run	CLAUDE_RESUME_DRY_RUN=1	off	Detect and log, but never actually type
--help-resume			Show help

CLAUDE_RESUME_BIN overrides auto-detection of the real claude binary.

# e.g. wait 60s past reset and nudge with a custom message
claude --resume-buffer 60 --resume-text "continue where you left off"

Test it

A built-in end-to-end test spins up a mock claude that hits a limit resetting in a few seconds and verifies the resume actually fires:

python3 claude_watcher.py --self-test

How it decides something is a limit

To avoid resuming on ordinary output that just mentions limits (this repo is about rate limits, after all), a trigger requires both a limit/error signal (usage limit, limit reached, 429, …) and a reset time or backoff duration within a small window of each other. Prose like "I'll be done in 5 minutes" or "add a rate limiter that resets at midnight" is ignored.