unsnooze

https://unsnooze.dev/docs
Admin
unsnooze is a CLI tool that automatically wakes and resumes limit-stopped AI coding sessions across...
Tokens:5,068
Snippets:57
Trust Score:2.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Setup Unsnooze

Source: https://unsnooze.dev/docs

Install the CLI globally and run the setup wizard to configure shell wrappers and hooks.

```bash
$ npm install -g unsnooze
$ unsnooze setup
```

--------------------------------

### Examples of host authentication setup

Source: https://unsnooze.dev/docs/fleet

Practical examples for configuring various password sources and testing host connectivity.

```bash
$ unsnooze hosts add laptop me@laptop.local --auth password
# → prompts (no-echo) every time it's used from a real terminal

$ unsnooze hosts add gpu ubuntu@gpu.example.com --auth password --source env --env UNSNOOZE_PW_GPU
# → export UNSNOOZE_PW_GPU=... first

$ unsnooze hosts add mac me@mac-mini.local --auth password --source keychain --service unsnooze-mac --account me
# → macOS only; reads via `security find-generic-password`

$ unsnooze hosts add ci ci@build.example.com --auth password --source command --cmd 'op read op://vault/ci/password'
# → any OS; runs your secret manager, reads its stdout

$ unsnooze hosts test gpu
# → resolves the credential + probes reachability; prints "auth ok" or a
#   hint ("needs-setup: ..."), never the secret
```

--------------------------------

### Verify Installation Health

Source: https://unsnooze.dev/docs

Check the status of the installation and daemon processes.

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

--------------------------------

### Install unsnooze on WSL

Source: https://unsnooze.dev/docs/fleet

Commands to install the required multiplexer and the unsnooze package on a WSL environment.

```bash
$ sudo apt install tmux        # or install Zellij
$ npm install -g unsnooze && unsnooze setup
```

--------------------------------

### Configure statusline shim

Source: https://unsnooze.dev/docs/commands

Installs or uninstalls the statusline shim to enable exact Claude percentage reporting.

```bash
$ unsnooze usage --install-statusline    # exact Claude % (chains your statusLine)
$ unsnooze usage --uninstall-statusline  # restore your original statusLine
```

--------------------------------

### Add a host with authentication configuration

Source: https://unsnooze.dev/docs/fleet

Syntax for adding a new host with specific authentication and credential source settings.

```bash
$ unsnooze hosts add <name> <dest>
      [--auth key|password]                  # default: key
      [--source prompt|env|keychain|command] # default: prompt, once --auth password is set
      [--env <VARNAME>]                      # env source: var to read (default UNSNOOZE_PW_<NAME>)
      [--service <s> --account <a>]          # keychain source (macOS only)
      [--cmd '<command>']                    # command source: program whose stdout is the password
```

--------------------------------

### Run development and testing commands

Source: https://unsnooze.dev/docs/troubleshooting

Execute unit tests, simulate end-to-end cycles, perform syntax checks, and regenerate demo assets.

```bash
$ 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)
$ bash -n scripts/e2e-zellij.sh # syntax-check the Zellij smoke test
$ vhs demo/demo.tape            # regenerate the demo gif (brew install vhs)
```

--------------------------------

### View unsnooze help documentation

Source: https://unsnooze.dev/docs/commands

Displays the full list of available commands and usage patterns for the unsnooze CLI.

```text
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)
```

--------------------------------

### Manage Local Queued Prompts

Source: https://unsnooze.dev/docs/commands

Commands for adding, listing, and removing prompts in the local environment.

```bash
$ 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
```

--------------------------------

### Manage Fleet Queued Prompts

Source: https://unsnooze.dev/docs/commands

Commands for queuing and listing prompts on remote registered hosts.

```bash
$ unsnooze prompt add --host gpu-box --project /home/me/repo --agent claude --now "..."
$ unsnooze prompt list --host gpu-box
```

--------------------------------

### Manage remote hosts and fleet sessions

Source: https://unsnooze.dev/docs/fleet

Commands for registering, listing, testing, and removing SSH hosts, as well as viewing fleet-wide session status.

```bash
$ unsnooze hosts add work you@work-box.local   # register an ssh destination
$ unsnooze hosts list                          # registered hosts
$ unsnooze hosts test work                     # pre-flight: credential + reachability
$ unsnooze hosts rm work                       # forget a host
$ unsnooze fleet [--json]                      # every host's sessions, fanned out over ssh
$ unsnooze dashboard fleet                     # live Fleet tab
```

--------------------------------

### Check usage forecast

Source: https://unsnooze.dev/docs/commands

Displays account burn rates and time-to-limit for configured models.

```bash
$ 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 burn
```

--------------------------------

### Configure ntfy push notifications

Source: https://unsnooze.dev/docs/settings

Sets the ntfy topic with a random hex string and configures privacy settings to exclude paths from push notifications.

```bash
$ unsnooze config set ntfyTopic "unsnooze-$(openssl rand -hex 8)"
$ unsnooze config set ntfyPrivacy terse   # keep paths out of push bodies
```

--------------------------------

### Manage Agent Interventions

Source: https://unsnooze.dev/docs

Perform manual interventions on agent sessions such as sending messages, forcing resumes, or cancelling tracking.

```bash
$ 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
```

--------------------------------

### Check Agent Status

Source: https://unsnooze.dev/docs

View the status of tracked agent sessions, including reset times and session details.

```bash
$ 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
```
Tokens:
Raw