Claude Supervisor: wait out Claude Code usage limits, then auto-resume

A developer built Claude Supervisor, an open-source tool that automatically resumes Claude Code sessions after usage-limit resets. The tool waits for real rate-limit resets without bypassing authentication or subscriptions, and tracks hours saved. It is available on PyPI and GitHub under an MIT license.

If you use Claude Code https://claude.com/claude-code for long, agentic tasks, you know the moment: you're mid-refactor, the agent is cooking, and then — usage limit. It stops. You come back an hour or two later, the reset has passed, and you manually pick up where you left off. I wanted to just… walk away and have it resume itself. So I built Claude Supervisor — a Important framing up front: it is not a bypass . It never touches authentication, subscriptions, or rate limits. It waits for real resets and respects every limit. That constraint shaped the entire design. pipx install claude-supervisor claude-supervisor init claude-supervisor start --task "add type hints across the package" Walk away. It runs the task, and if you hit a limit it waits out the reset and continues. When you're back: bash $ claude-supervisor status total sessions 5 resumes 4 hours saved 20.0 It even tracks "hours saved" — the unattended waiting it did on your behalf. Claude Supervisor launches the claude CLI inside a pseudo-terminal PTY and reads its output stream. A small set of regex rules — living in external YAML , not code — recognize four things: a usage limit, a permission prompt, STARTING → RUNNING ⇄ WAITING FOR PERMISSION │ ├→ WAITING FOR RESET → RESUMING → RUNNING │ └→ TASK COMPLETED → STOPPED Two design choices I'm happy with: TASK COMPLETED has exactly one exit: STOPPED . There is no transition back to RUNNING , so the supervisor I built the whole thing test-first with a scripted fake terminal: 180+ tests, high coverage, all green. Feeling good, I ran it against a real Windows pseudo-console for the first time. Two bugs surfaced within minutes that no unit test had caught: ANSI escape sequences. A real PTY and Claude's TUI interleaves colour and cursor codes into the stream — \x1b 32m…\x1b 0m . My patterns matched raw lines, so coloured output could dodge detection. Fix: strip ANSI before matching. Carriage return vs. line feed. To answer a prompt I sent "y\n" . On a Windows ConPTY, \n is not the Enter key — so the child process sat blocked on input forever and the whole run hung. The Enter key is \r . One character. That was the lesson of the project: a green test suite is necessary, not sufficient. The real terminal is the source of truth. I turned that first real Because the supervising runs from your shell, I surfaced its status inside the Claude Code UI two ways: a status line 🛡 3 runs · 1 resume · 2.1h saved and a /supervisor slash command. Both read the same local SQLite history. It's an early alpha — but a serious one: validated end-to-end against real Claude Code, CI on Windows + Linux across Python 3.12–3.14, MIT licensed, published on PyPI. pipx install claude-supervisor --capture run.txt and open an issue.If you've ever lost momentum to a usage limit, I'd genuinely love your feedback. Stars, issues, and "here's what broke for me" all welcome. ⭐