documentation
Command reference
Every command, the usage forecast that tells you when the wall arrives, and the prompt queue that starts the next piece of work as a fresh session.
Command reference
Verbatim from unsnooze help (current main):
unsnooze — wakes every limit-stopped AI coding session when the limit resets
Usage:
unsnooze [claude args...] run claude under limit-watch (default)
unsnooze _run <agent> [args...] run a specific agent CLI under limit-watch
unsnooze status list tracked sessions + reset countdowns
unsnooze resume-now [id|--all] resume stopped session(s) immediately
unsnooze cancel [id|--all] stop tracking session(s)
unsnooze message <id|--all> <t> set a per-session wake message (--clear to reset)
unsnooze sessions list unsnooze-owned mux sessions + panes
unsnooze reap [--dry-run|--yes] close terminal-record panes / empty sessions
(default: dry-run; pass --yes to apply)
unsnooze doctor [--fix] check install health; find (and with --fix
retire) leftovers of the old
claude-session-guard install
unsnooze preview [id] dry-run: what WOULD happen right now, and
why — nothing is typed or opened (exit 2
when a wake is actionable, else 0)
unsnooze dashboard [tab] live TUI (status|usage|sessions|doctor|logs|fleet|prompts)
— q to quit, mouse: click/wheel (m toggles)
unsnooze hosts [add|rm|list] register ssh hosts for the fleet view
add <name> <dest> [--auth key|password]
[--source prompt|env|keychain|command]
[--env VAR] [--service s --account a]
[--cmd '<command>']
unsnooze hosts test <name> pre-flight a host: resolves its credential
and probes reachability (secret never shown)
unsnooze fleet [--json] all hosts' sessions (hosts add <name> first)
unsnooze prompt add [text...] queue a prompt to start a NEW session in a
project when the limit resets ([--agent id]
[--project path] [--at time|--now])
unsnooze prompt list [--json] list queued prompts
unsnooze prompt remove <id> cancel a queued prompt
unsnooze prompt clear cancel all pending queued prompts
unsnooze usage [--json] account burn rate & time-to-limit forecast
(--install-statusline for exact Claude %,
--uninstall-statusline to remove it)
unsnooze logs [-f] show (or follow) the unsnooze log
unsnooze update update unsnooze itself to the latest version
unsnooze daemon persistent watcher for GUI sessions (VS Code
extension, desktop apps) — no live pane needed
to detect; revival opens in tmux or Zellij
unsnooze config [list|get|set] view or change settings (toggles, global +
per-agent resume messages, notifyChannel
auto|native|osc|bell, updateCheck)
unsnooze setup interactive setup wizard (agents + toggles)
unsnooze install [--yes] wire up shell wrappers + hooks (non-interactive)
unsnooze uninstall [--purge] remove wrappers + hooks (and state with --purge)
unsnooze report [agent] [pane] capture a pane to report an undetected banner
unsnooze help show this help (also -h / --help)Usage forecast
Recovery is half the job; unsnooze usage is the other half — knowing when the wall is coming so you can /compact, pause, or switch models first.
$ unsnooze usage
unsnooze usage — account burn & time-to-limit (daemon: running · warnings at 80,95%)
claude 5h [█████████████░░░░░░░] ~64% (calibrated from 4 stops)
burn ~31k weighted tok/min over last 42 active min
wall ~1h 10m at this pace · window resets 8:00 pm (absolute)
codex 5h [███░░░░░░░░░░░░░░░░░] 5% used (exact)
monthly [██░░░░░░░░░░░░░░░░░░] 5% used (exact) · resets Aug 11
burn idle — no active burnEvery figure carries its provenance — never a bare percentage:
(exact)— Codex always (localused_percent+ epoch reset). Claude only with the opt-in statusline shim, which persists Claude Code's server-authoritative rate limits.(calibrated from N stops)— Claude token burn against a ceiling learned from your recorded limit stops. Not plan presets.(estimated — calibrating, needs one observed limit stop)— used tokens + burn shown; the ceiling stays unknown until the first observed stop.
$ unsnooze usage --install-statusline # exact Claude % (chains your statusLine) $ unsnooze usage --uninstall-statusline # restore your original statusLine
With the daemon running, warnings fire at the usageWarnAt percent bands and at 30 / 10 minutes to the wall at your current pace, deduped once per window. Warnings may suggest /compact; unsnooze never auto-types it. usage --json emits a stable machine shape and exits 2 past the warn threshold — useful in scripts and statuslines.
Honest limits: Claude transcript sums are a lower bound — subscription quotas are account-pooled with claude.ai and the desktop app. Without the shim, Claude tops out at calibrated/estimated.
Queued prompts
Queue a prompt now; unsnooze types it into a brand-new agent session — a fresh window in a project directory — once a usage limit clears (or at a time you choose). It's one-shot: each entry is delivered at most once.
$ unsnooze prompt add "run the full test suite and fix any failures" # → interactive agent picker on a TTY; queued for next-reset in the cwd $ unsnooze prompt add --agent codex --project ~/code/api --now "ship the release" $ unsnooze prompt add --at "+2h30m" "rebase onto main" # relative duration $ unsnooze prompt add --at "9pm" "nightly cleanup pass" # next occurrence of a clock time $ unsnooze prompt add --at 1755000000 "..." # epoch (seconds or ms), or an ISO-8601 timestamp $ unsnooze prompt list [--json] # id, agent, due, status, cwd, prompt preview $ unsnooze prompt remove <id> # cancel one pending/launching entry $ unsnooze prompt clear # cancel every pending/launching entry
Modes
- next-reset (default) — delivered once no future reset time is known for that agent, i.e. once the current limit clears. If unsnooze holds no reset signal at all for that agent when you add the entry, there's nothing to wait on — it delivers on the very next daemon tick, and
prompt addprints a notice to that effect right away. Use--atif you want a specific time instead. --now— deliver on the next daemon tick, no reset wait at all.--at <time>— deliver at a specific time: epoch (seconds or milliseconds), an ISO-8601 timestamp, a+2h30m-style relative duration, or a bare clock time (9pm,2:05pm,14:30) rolled to its next local occurrence.
If a delivery attempt lands on a pane that's still limited — the reset hadn't actually cleared, or a fresh --now/--at session hits the wall immediately — the entry goes back to pending behind a backoff floor before it's retried. That floor applies to every mode, so a failing --now/--at entry can't burn through every retry in the first few seconds. Verified delivery (capped at 5 attempts, same as resume) marks it failed and sends a notification.
autoResume does not gate prompt delivery — the queue runs independently of session tracking, even with autoResume off.
Fleet
--host <name> queues on a registered host instead of locally. --project (an absolute remote path) and --agent are both required — there's no local cwd to default to and no interactive picker over an ssh round-trip. The remote host re-validates everything server-side. Delivery feedback comes from unsnooze fleet / the dashboard's Fleet tab (per-host queued count) and that host's own notifications (ntfy reaches your phone from any host, not just the one you're sitting at). A host can refuse all queue traffic with remoteQueue: false (unsnooze config set remoteQueue off, env UNSNOOZE_REMOTE_QUEUE=0, set on the host being controlled) — the queue verbs then answer a typed "disabled" instead of silently dropping; a remote that predates this feature reports a clear "too old" error instead of failing silently.
$ unsnooze prompt add --host gpu-box --project /home/me/repo --agent claude --now "..." $ unsnooze prompt list --host gpu-box
Dashboard
The Prompts tab (7) lists queued entries; a opens an add form (path → agent → when — with a time prompt if you pick "at" — → a host step if you have hosts registered → prompt text), d/x removes the selected entry. The Status tab shows a <n> prompt(s) queued — tab 7 hint whenever entries are pending or launching.