If you use 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:
$ 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. ⭐