Install and setup

Getting started

You need Node ≥ 20 and tmux ≥ 3.2 or Zellij, on macOS, Linux, or Windows via WSL.

$ npm install -g unsnooze
$ unsnooze setup

The setup wizard asks which agents to guard and which toggles you want, then wires everything up:

• Shell wrappers into ~/.zshrc / ~/.bashrc — after this, typing claude or codex runs the CLI inside a watched multiplexer pane. You never call unsnooze directly to be protected.
• The Claude StopFailure hook — the authoritative limit-stop signal, carrying the session id.
• Optionally the daemon (a launchd agent on macOS, a systemd user unit on Linux) for GUI-surface watching and pre-wall usage warnings.
• ~/.unsnooze/config.json with your choices — see Settings.

Every file it touches is backed up first (*.unsnooze-orig pristine, *.unsnooze-bak rolling), and unsnooze uninstall removes every change. Verify the install any time with unsnooze doctor — it reports problems, not a checklist, so a healthy install is a one-liner:

$ unsnooze doctor
unsnooze doctor: all clear — install is healthy.
  · resumer/daemon: running (pid 4821)

Anything wrong comes back as a ✗ finding with a suggested fix, and doctor --fix repairs what it safely can. One nuance on requirements: tmux version isn't checked — any tmux runs, but reviving dead sessions uses env flags that need tmux ≥ 3.2.

Day to day

Run your agents like always. When one hits its limit, unsnooze records the stop in ~/.unsnooze/state.json — agent, session id, working directory, pane, and the reset time parsed from the banner — and wakes it when the limit lifts.

$ unsnooze status
  [STOPPED  ] f3a1c2d4  claude 5h      /Users/you/work/payments
              mux tmux · pane %12 · session unsnooze · via hook · resets 19/7/2026, 3:00:00 am (2h 41m) (absolute, from hook) · attempts 0/5 · ctx ~152k tok
  [RESUMED  ] 92d6f63d  claude 5h      /Users/you/oss/unsnooze
              mux tmux · pane %7 · session unsnooze · via cli · resets 18/7/2026, 4:11:00 pm (due now) (absolute, from scrape) · attempts 1/5 · attach: tmux attach -t unsnooze

Each session is two lines: a header (status, 8-char id, agent, limit window, working directory) and a detail line (pane, how the stop was detected, the reset time with countdown and its provenance, attempts out of 5, plus ctx ~152k tok on stopped sessions and an attach hint on live ones). Statuses are stopped, resuming, resumed, cancelled, and failed.

On an interactive terminal, status, usage, and sessions open the live dashboard instead; pipes, CI, NO_COLOR, and --json stay plain. The common interventions:

$ unsnooze message f3a1 "Run the tests first, then continue."
$ unsnooze resume-now f3a1     # don't wait for the reset time
$ unsnooze cancel --all        # stop tracking everything

Not sure what it's about to do? unsnooze preview is a true dry-run: it prints exactly what would be typed, where, and why — or what's holding it back — and sends nothing. It shares its decision code with the real dispatcher, so it cannot drift from what dispatch actually does. It exits 2 when a wake is actionable right now, 0 otherwise — scriptable.

The rest of the docs

Setup is the whole of the required reading. Everything else is here when you need it:

• Command reference — every command with real output, the unsnooze usage forecast that tells you when the wall arrives, and the prompt queue that starts the next piece of work as a fresh session.
• Settings and guards — every key in ~/.unsnooze/config.json, the guards that decide when not to wake a session, and how notifications reach you.
• SSH multi-host fleet — watch limit-stopped sessions on every machine you code on, plus GUI surfaces and platform support.
• Troubleshooting and security — when a wake did not happen, what unsnooze doctor reports, and the threat model.

Shipped releases and the reasoning behind each change live in the changelog; anything missing or wrong is worth reporting.