unsnooze

Claude Code · Codex CLI · Grok · Qwen · Kimi · OpenCode · Antigravity — 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 or Zellij the moment the usage limit resets.

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:

Trust & security

unsnooze is a scheduler that presses your keys — not an auto-approver. It waits for your usage limit to reset, then resumes the same session. It never changes how your agent handles permissions.

• Types only after proving the pane is yours. Every keystroke requires both identity (a tmux @unsnooze_owner stamp, else a lease = process id + birth time — a mismatch vetoes, because pane ids get recycled) and liveness (your agent is still running there). Pane closes require proven identity (idle threshold too for resumed panes). Ownership unprovable → it reopens a fresh session instead of typing.
• See before you trust: unsnooze preview. A true dry-run — it prints exactly what would be typed, where, and why (or what's holding it back), and sends nothing. Preview shares its decision code with the real dispatcher, so it cannot drift from what dispatch actually does.
• Answers Claude's limit menu safely — never a blind Enter. It locates the cursor and the "Stop and wait for limit to reset" option and computes the exact moves. Unreadable menu → it presses nothing. It will never select "Upgrade your plan." Toggle with menuAutoAnswer.
• No --dangerously-skip-permissions, no auto-trust, no auto-approve. unsnooze never passes bypass flags, never presses "Yes, I trust this folder," and never touches MCP config. Whatever your agent does after resuming is governed by its own permission model — the same as if you'd typed the message yourself.
• Nearly zero network, zero telemetry. One version check to registry.npmjs.org (nothing identifying; updateCheck=false turns it off), and push notifications only if you configure an ntfy topic. State stays local under ~/.unsnooze.
• Reversible install. The settings hook and rc-file wrappers are backed up first (*.unsnooze-orig pristine + *.unsnooze-bak rolling); unsnooze uninstall removes every change. Releases are published with npm provenance.
• Fleet adds no network surface. No listening ports, no custom auth, no tokens. Transport is your own OpenSSH (~/.ssh/config, keys, agent); unsnooze never sets StrictHostKeyChecking=no and fails fast on unknown hosts instead of auto-trusting them.
• The remote is the authority. Fleet resume only marks a session due — the remote daemon types under its own gates (foreground, idle, your configured message only). A compromised viewer cannot make a remote type anything else.
• Remote output is untrusted. Everything a host returns is control-character-stripped and length-capped before it touches your terminal (ANSI-injection defense), and parsed fields are extracted — never merged — into fresh objects.
• Lock a key to unsnooze (optional, recommended for automation): command="unsnooze _remote",restrict ssh-ed25519 AAAA… unsnooze-fleet in the remote authorized_keys confines that key to the fleet entrypoint — it can never open a shell.

Honest limits: unsnooze does inject keystrokes into your live terminal on your behalf, and it does not sandbox your agent or defend against prompt injection / malicious repos — that's your agent's job. Full threat model, residual risks, and vulnerability reporting: SECURITY.md.

Supported CLIs

• Claude Code — dual-channel detection: the StopFailure hook (authoritative, carries session_id) plus multiplexer 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.
• Qwen Code — ⚠️ experimental. Dual-channel: a Claude-shaped StopFailure hook installed into ~/.qwen/settings.json (fires with error: rate_limit) plus scraping for the verbatim quota renders (Qwen OAuth quota exceeded, Coding Plan Allocated quota exceeded, and OpenRouter Rate limit exceeded: limit_… passthroughs). Qwen never shows a reset time, so waits use the 5-hour fallback and self-correct on verify. Dead sessions revive via qwen --resume <id> (session ids come from the *.runtime.json sidecars qwen writes for exactly this purpose).
• Kimi CLI (Moonshot) — ⚠️ experimental. Scrape-based: kimi retries a 429 three times within seconds, then stops with a red LLM provider error: Error code: 429 … rate_limit_reached_error line — that's the detection anchor. The 429 body carries no reset time (5h fallback + verify). Dead sessions revive via kimi -r <id> -p "<message>" — with a guard: kimi silently starts a new session for unknown ids, so the id is verified on disk first (--continue otherwise). Membership expired (402) is notify-only.
• OpenCode — ⚠️ experimental, and a different shape: OpenCode retries rate limits itself, forever, honoring retry-after (it will sleep hours until the reset, showing Rate Limited [retrying in 2h5m attempt #4]). So unsnooze records the stop but never touches a live self-retrying pane; its job is reviving sessions whose process died mid-wait (laptop slept, tmux gone) via opencode -s <ses_id>, with the reset time parsed straight from the banner countdown. Zen plan banners (5 hour/weekly/monthly usage limit reached…) and OpenRouter passthroughs are detected too; insufficient credits (402) is notify-only.
• Antigravity CLI (Google, agy) — ⚠️ experimental. The Gemini-CLI successor. Scrapes the forum-reported quota strings (Model quota limit exceeded, Refreshes in 6 days and 18 hours — parsed, multi-day refresh = the weekly cap) and treats 503 MODEL_CAPACITY_EXHAUSTED as a transient overload, not a limit. Dead sessions revive via agy --conversation=<id> (ids from ~/.gemini/antigravity-cli/history.jsonl). Like Grok: closed source, so unsnooze report captures make this adapter better.

OpenRouter (the API gateway) isn't a separate agent: its 429 bodies (Rate limit exceeded: limit_rpd/…, free-models-per-day) are detected inside the CLIs that use it (OpenCode, Qwen Code), and credit exhaustion (402) is surfaced as a notification — there's no reset to wait for, only a top-up.

GUI surfaces (VS Code extension, desktop apps)

Terminal sessions are watched through the shell wrapper + tmux or Zellij. 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 the unified ChatGPT desktop app (July 2026: the Codex app became the ChatGPT app; its bundled codex app-server writes the same rollouts to the same store — verified against a real install). On machines where Codex lives only inside ChatGPT.app (no codex on PATH), unsnooze automatically resumes through the app-bundled binary (`/Applications/ChatGPT.app/Conten