Hit your session limit? Go do something else.
claude-auto automatically waits out the reset and continues right where you left off.
claude-auto is a transparent wrapper around the Claude Code
CLI. It runs claude inside a pseudo-terminal and forwards your keystrokes and
Claude's output untouched, so the TUI looks and behaves exactly as it always has.
The difference: when Claude reports that you've hit your session limit, claude-auto sends
a quick /usage command to confirm the limit, counts it down in your window title, and sends continue
the moment your quota is back. No babysitting, no lost context.
The package is published to npm as @hotox/claude-auto.
npm install -g @hotox/claude-autoMore package managers
bun add -g @hotox/claude-auto
pnpm add -g @hotox/claude-auto
yarn global add @hotox/claude-autoOr run it without installing anything — handy for trying it once:
npx @hotox/claude-auto # or: bunx @hotox/claude-autoNote that npx/bunx re-resolve the package on each run, so they're slower to
start than a global installation, and they can't be aliased to claude, but it uses the
latest version of claude-auto on every run.
npm never updates a global install on its own, so you stay on the version you installed until you say otherwise:
npm install -g @hotox/claude-auto@latestclaude-auto checks for a new version once a day in the background and, if one
exists, prints a one-line reminder after Claude exits — never during a
session, where it would corrupt the TUI. Set CLAUDE_AUTO_NO_UPDATE_CHECK=1 to
turn the check off entirely.
claude-auto is a drop-in replacement for claude. All user arguments are forwarded directly to the real CLI:
claude-auto # same as `claude`
claude-auto -p "explain this" # same as `claude -p "explain this"`
claude-auto --permission-mode plan # same as `claude --permission-mode plan`To make claude always start claude-auto automatically:
claude-auto --install-alias # --uninstall-alias to undo itIt writes the alias into your shell's startup file (~/.zshrc, ~/.bashrc,
config.fish, PowerShell's $PROFILE. it picks the right one and tells you
which), so every new shell has it. Safe to re-run. Open a new shell afterwards.
Not supported for cmd.exe: doskey has no startup file, so a permanent macro
needs a registry key that runs for every cmd session on the machine. Use
PowerShell.
claude-auto sessions start automatically in auto mode. A wrapper whose whole
job is to keep working while you're away shouldn't then stop to ask permission
for every tool call, so claude-auto passes --permission-mode auto for you.
Here are three ways to override this:
claude-auto --no-auto-mode # starts Claude using the default mode
claude-auto --permission-mode plan # starts in any mode (here in plan mode)
claude-auto --dangerously-skip-permissions
Press F4 while a countdown is running to cancel it and hand the session back to you. Detection re-arms immediately, so the same limit can be picked up again.
- On macOS, F4 is a system key unless
Use F1, F2, etc. keys as standard function keysis enabled in Settings, so countdown cancelling may not reach the wrapper.
MIT © Philipp Köhler
Dev Notes
claude-auto owns these flags. None of them reach claude; everything else you
pass goes to it verbatim.
| Flag | Effect |
|---|---|
--no-auto-mode |
Don't pass --permission-mode auto. Makes it start in claude's own default mode |
--install-alias |
Write claude → claude-auto into your shell's startup file |
--uninstall-alias |
Remove that alias again |
--auto-debug |
Append rendered-screen snapshots and detection decisions to claude-auto.log |
The first two are stripped before forwarding and the session runs as usual. The alias flags don't start a session at all: they edit the file, report what they did, and exit.
| Variable | Effect |
|---|---|
CLAUDE_AUTO_NO_UPDATE_CHECK |
Set to 1 to disable the daily update check and the exit notice |
Every 2 seconds, claude-auto snapshots the rendered screen, the grid of
characters actually on display, mirrored into a headless
xterm, rather than the raw escape-sequence
stream. That means it sees what you see, and isn't fooled by redraws, spinners,
or partial writes.
When a session-limit banner appears:
- If Claude is offering its "Stop and wait for limit to reset" menu, it selects that option for you.
- Otherwise it confirms the limit against
/usage. It opens Claude's/usagepanel and reads the Current session blocks percent used and reset time. Only a bar at 100% used confirms the limit, so a stale banner on screen can't trigger a false positive. If the window is too small to show the block, the panel is scrolled step by step until both values have been read. Then the panel is closed with Esc. - Then it waits. It counts down to the reset time reported by
/usage(plus a one-minute safety buffer) — more precise than the rounded time in the banner — showing the remaining time in your window title, and sendscontinuewhen the clock runs out.
Overload errors (● API Error: 529) are handled the same way, minus the
verification: there's no quota involved, so there's nothing /usage could
confirm. claude-auto just counts down five minutes and sends continue. If the
error comes back, so does the countdown. A session-limit banner takes precedence
— when you're out of quota, retrying in five minutes would only hit the limit
again.
Some more details:
- Detection is skipped entirely while you're scrolled up through history, what's on screen there is stale.
- Nothing is typed while Claude is asking whether to resume a long session from
a summary ("Resume from summary (recommended)" / "Resume full session
as-is"). If a countdown runs out while the question is up,
claude-autoholds and resumes the moment you've answered. - A reset that's already been counted down to is ignored if the same banner reappears, until enough time has passed that it must be a genuinely new limit.
- A banner that
/usagedisproves (session below 100%) is remembered by its reset time and is ignored until a real limit is hit, or after 3 hours, whichever comes first. - The weekly rows in
/usagealso say "% used", but only text between the Current session heading and the next section is ever parsed, so they can't be mistaken for the session bar. - Nothing is ever written to stdout or stderr. That would corrupt the TUI, so all diagnostics go to the optional log file.
bun install
bun run claude # run from source via tsx
bun run typecheck # tsc --noEmit
bun run build # emit dist/claude-auto.jsThe run path uses tsx, which transpiles
without type-checking, so bun run typecheck is a separate step.
On Windows, claude-auto.cmd runs the local source without installing anything. |
The package is published to npm as @hotox/claude-auto.
Releases are cut by .github/workflows/release.yml
on every push to main, but only when version in package.json changes,
an ordinary push is a no-op. To cut a release, bump version and push to main.
The workflow type-checks, builds, publishes to npm, tags v<version>, and creates
a GitHub Release with generated notes.
It needs an npm automation token in the repo secret NPM_TOKEN (gh secret set NPM_TOKEN).