unsnooze

Claude Code · Codex CLI · Grok — when they hit the 5-hour or weekly usage limit ("You've hit your usage limit"), your session just… stops.
unsnooze auto-resumes them: it tracks every limit-stopped session across all your projects and wakes each one up in tmux the moment the usage limit resets.

copy

npm install -g unsnooze && unsnooze setup

Why unsnooze

Overnight and long-running agent work dies at the 5-hour / weekly limit, and every existing tool solves only a slice of it:

Supported CLIs

• Claude Code — dual-channel detection: the StopFailure hook (authoritative, carries session_id) plus tmux pane scraping for banners and the interactive limit menu (always answered with "Stop and wait for limit to reset", never a blind Enter). Dead sessions revive via claude --resume <id>.
• OpenAI Codex CLI — scrape-based (Codex fires no event on limits). Detects the exact ■ You've hit your usage limit … banner strings from the Codex source, parses try again at 3:51 PM / Feb 23rd, 2026 9:01 PM / in 4 days 20 hours 9 minutes. Dead sessions revive via codex resume <id> "<message>" — the prompt travels in argv.
• Grok Build (xAI) — ⚠️ experimental. Hook channel works (Grok reads Claude-compatible hooks, including StopFailure); the limit banner text is not publicly documented, so detection uses generic patterns with a safe fallback. Hit a banner unsnooze missed? Run unsnooze report and paste the capture into an issue — that's how this adapter gets good.

GUI surfaces (VS Code extension, desktop apps)

Terminal sessions are watched through the shell wrapper + tmux. Sessions in Claude Code's VS Code extension / desktop app and Codex's IDE extension / desktop app have no pane to scrape — so unsnooze daemon tails the session files those surfaces already write:

• Claude Code records every rate-limit stop as a structured entry in its ~/.claude/projects/**.jsonl transcript (session id, cwd, reset time) — shared by the CLI and the VS Code extension.
• Codex writes a rate_limits snapshot (usage %, exact epoch reset time) into every rollout under ~/.codex/sessions/ — shared by the CLI, IDE extension, and desktop app.
• Claude desktop (cowork) sessions (experimental, macOS) run in sandboxes under ~/Library/Application Support/Claude; unsnooze watches those too and revives with the session's isolated CLAUDE_CONFIG_DIR (plus the keychain-scope override that keeps auth working — verified against a real desktop session).

When the limit resets, the session is revived in a tmux window with claude --resume <id> / codex resume <id> — it's the same session file, so the continued conversation stays visible in the GUI's own history. (Resuming inside the GUI panel isn't possible today: no extension/app exposes an IPC/URI that can send a prompt.)

Enable it in unsnooze setup (installs a launchd agent / systemd user unit), or run unsnooze install --daemon / unsnooze daemon yourself. Turn it off anytime with unsnooze config set guiWatch off.

How it works

claude / codex / grok (shell wrapper) ──► unsnooze _run <agent> ──► CLI in tmux pane
                                              │
                                              ├─ per-pane monitor (scrapes for limit
                                              │  banners, drives Claude's limit menu,
                                              │  seconds-scale retry on 5xx/overload)
                                              │
StopFailure hook (claude, grok) ──────────────┤
                                              ▼
                                ~/.unsnooze/state.json
                                { agent, sessionId, cwd, pane, resetAt, status }
                                              │
                                              ▼
                                resumer daemon (singleton, epoch-polling —
                                survives laptop sleep and weekly-scale waits)
                                              │
                          ┌───────────────────┴────────────────────┐
                 pane still alive?                          pane gone?
                 send resume message into it                tmux new-window,
                 (only if the CLI is foreground             `unsnooze _run <agent>
                 and not mid-stream)                        --resume <id>`, verify

Limit events are never persisted by the CLIs themselves; the reset time is parsed from the banner text, DST-safe, with a 5-hour fallback when unparseable — and every resume is verified afterwards (banner came back → reschedule from the fresh banner, capped at 5 attempts).

Usage

claude / codex / grok           # normal usage — wrapped automatically
unsnooze status                 # tracked sessions + reset countdowns
unsnooze resume-now [id|--all]  # don't wait for the reset time
unsnooze cancel [id|--all]      # stop tracking a session
unsnooze message <id> "text"    # per-session wake message (--clear to reset)
unsnooze config list            # settings (see below)
unsnooze config set <k> <v>     # e.g. autoResume off
unsnooze logs [-f]              # what unsnooze has been doing
unsnooze update                 # update unsnooze itself
unsnooze daemon                 # persistent GUI-session watcher (usually run
                                # by launchd/systemd via `install --daemon`)
unsnooze report [agent]         # capture a pane to report an undetected banner
unsnooze uninstall [--purge]    # remove wrappers + hooks (+ state with --purge)
unsnooze help                   # full command list (also -h / --help)

Settings

unsnooze setup writes ~/.unsnooze/config.json; change anything later with unsnooze config set:

Every setting also has a UNSNOOZE_* env override (see src/settings.js), and all timings/paths are tunable via UNSNOOZE_* env vars (see src/config.js).

Safety properties

• Never injects blind: keys are only sent when the pane's foreground process is the agent CLI and no "esc to interrupt"-style busy footer is visible. Recycled pane ids can't receive stray messages.
• Never picks a menu option blind: if Claude's limit menu layout can't be read, unsnooze does not press Enter (that could confirm "Upgrade your plan").
• Sleep-safe waits: the resumer polls wall-clock against the target epoch every 30s instead of one long timer — a laptop asleep past the reset fires on the next tick. Weekly limits are just a bigger epoch.
• Verified resumes: after dispatch it re-captures the pane; if the limit banner reappears (reset time misparsed / not actually reset), it reschedules from the fresh banner, capped at 5 attempts.
• Concurrent-writer safe: state updates go through a mkdir lock + atomic rename; corrupt state is quarantined, never fatal (the hook path must never block the CLI).
• Overload ≠ limit: 5xx/529/429 transient errors take a seconds-scale backoff path ([30,60,120,240,300]s ± jitter) and never enter the ledger.
• Stale-workspace guard: the repo's HEAD + dirty state are fingerprinted when a session stops. If another session (or you) changed the repo before the wake, the resumed agent is told to re-read before acting — or, with workspaceGuard=pause, the session is held and unsnooze resume-now shows the diff first.

Requirements

• Node ≥ 20 and tmux
• macOS, Linux, or Windows via WSL (see below)
• zsh or bash (the wrappers are installed into ~/.zshrc / ~/.bashrc)

Windows / WSL

unsnooze is built on tmux, so on Windows it runs inside WSL — which is where the agent CLIs live on Windows anyway:

# inside your WSL distro (Ubuntu etc.)
sudo apt install tmux
npm install -g unsnooze && unsnooze setup

Everything works as on Linux, including desktop notifications: inside WSL, unsnooze raises native Windows toasts through powershell.exe (no notify-send or X server needed). Native Windows (PowerShell/cmd, no WSL) is not supported — without tmux there is nothing to watch; unsnooze will tell you so and run your CLI unwatched instead of breaking it.

FAQ

What does "You've hit your usage limit" mean in Claude Code?

Claude subscription plans meter usage in a rolling 5-hour window plus a weekly cap. When either runs out, Claude Code stops mid-task and shows the banner with a reset time ("resets 3pm"). Nothing is lost — the session can be resumed with claude --resume <id> once the limit resets. unsnooze does exactly that, automatically, for every stopped session.

What about Codex — "You've hit your usage limit. Try again at …"?

Same idea: ChatGPT-plan Codex has 5-hour and weekly windows. The Codex TUI stays open at the composer after the banner, so unsnooze either types into the live pane or reopens the session with codex resume <id> at the reset time it parsed from the banner.

Does this get around the rate limit?

No. unsnooze waits for the reset exactly like you would, resumes once, and verifies the limit actually lifted. It replaces the 4am alarm, not the limit.

How do I update, and how do I know when to?

unsnooze update (or npm i -g unsnooze). unsnooze checks the npm registry at most once a day and tells you when a newer version exists (a line after CLI commands, plus one desktop notification per version); after updating, the next command shows a short "what's new" from the changelog. It's a plain registry GET with nothing identifying — turn it off with unsnooze config set updateCheck off.

What if another session changed the repo while one was stopped?

unsnooze fingerprints the workspace (HEAD + uncommitted state) at stop time and re-checks at wake. By default the session still resumes, but the wake message includes what changed ("HEAD abc1234 → def5678 — re-read before continuing"). Set workspaceGuard to pause to hold such sessions for a manual unsnooze resume-now (which prints the diff stat), or off to disable the check.

Does it work if my laptop was asleep or the terminal was closed?

Yes — reset times are stored as absolute timestamps and checked every 30 seconds, so a laptop that slept through the reset resumes on the next tick, and dead panes are reopened by session id in a fresh tmux window.

Development

npm test                     # unit tests (node:test)
./scripts/e2e-simulate.sh    # full detect → wait → re-open cycle in a
                             # scratch tmux session (no real limits needed)

License

MIT