unsnooze 1.16.0 → 1.16.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.16.1 — 2026-08-16
+
+- **`unsnooze status` no longer offers an attach command for headless sessions.**
+  A headless "pane" is a detached pid, but the attach hint fell through to the
+  default `tmux attach -t <session>` — a command that at best does nothing and
+  at worst attaches to an unrelated tmux session that happens to share the name.
+  Headless output lives in `~/.unsnooze/headless/<session>.log`, and status now
+  says nothing rather than something wrong. Found while building the capability
+  table for the new **[Supported terminals](https://unsnooze.dev/docs/#terminals)**
+  docs section, which sets out exactly what each of tmux, Zellij, herdr, cmux
+  and headless does and does not do.
+
 ## 1.16.0 — 2026-08-16
 
 - **Claude Design, and native Windows along the way.** ([#13](https://github.com/saaranshM/unsnooze/issues/13))

package/README.md

@@ -665,6 +665,38 @@ watcher stops (no pane context) always use native.
 - zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), or PowerShell
   (wrappers go into `$PROFILE.CurrentUserAllHosts`)
 
+### Supported terminals
+
+unsnooze drives four terminal multiplexers, and works without one.
+
+| | [tmux](https://github.com/tmux/tmux) ≥ 3.2 | [Zellij](https://zellij.dev) | [herdr](https://herdr.dev) ≥ 0.8.0 | [cmux](https://cmux.dev) | `headless` |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Detect a limit stop | pane + hook + transcript | pane + hook + transcript | pane + hook + transcript | pane + hook + transcript | hook + transcript |
+| Resume a live session in place | ✅ | ✅ | ✅ | ✅ | — |
+| Answer Claude's limit menu | ✅ | ✅ | ✅ | ✅ | — |
+| Revive a session whose pane died | ✅ | ✅ | ✅¹ | ✅² | ✅³ |
+| Wrap a bare `claude` into a managed session | ✅ | ✅ | ✅ | — | n/a⁴ |
+| `unsnooze reap` idle sessions | ✅ | ✅ | ✅ | — | — |
+| `attach:` hint in `unsnooze status` | ✅ | ✅ | ✅ | — | — |
+| OSC notifications to your terminal | ✅ | — | — | — | — |
+
+¹ Into a fresh session name (`unsnooze-2`), never by restarting the stopped one —
+herdr restores saved agent panes itself, so a revival on top would resume the
+same conversation twice.
+² Into a fresh workspace; cmux has no joinable named-session model.
+³ As a detached process. Its output goes to `~/.unsnooze/headless/<session>.log`,
+since there is no scrollback to read it out of later.
+⁴ Nothing to wrap into — your own terminal is the session.
+
+Pick one explicitly with `unsnooze config set multiplexer tmux|zellij|herdr|cmux|headless`.
+On `auto`, unsnooze uses the multiplexer you are currently inside; failing that,
+the only one installed (tmux breaks ties); failing that, `headless`.
+
+**Install:** `brew install tmux` or `brew install zellij` on macOS,
+`sudo apt install tmux` on Linux/WSL. herdr comes from
+[herdr.dev](https://herdr.dev) — Homebrew still ships 0.7.3, which `available()`
+refuses, so take the release binary.
+
 ### Watching without a multiplexer
 
 A terminal pane is only one of unsnooze's three detection channels. The Claude

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, and Antigravity sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",

package/src/multiplexers/session-name.js

@@ -52,6 +52,11 @@ export function attachHint(muxName, sessionName) {
   // is no command that attaches to a surface from outside cmux, so omit the
   // hint rather than print a `tmux attach` that would silently do nothing.
   if (muxName === 'cmux') return null;
+  // headless has no session at all — its "pane" is a detached pid. The default
+  // below would print `tmux attach -t <name>`, which at best does nothing and
+  // at worst attaches to an unrelated tmux session that happens to share the
+  // name. Its output lives in ~/.unsnooze/headless/<session>.log instead.
+  if (muxName === 'headless') return null;
   if (muxName === 'herdr') return `herdr session attach ${sessionName}`;
   if (muxName === 'zellij') return `zellij attach ${sessionName}`;
   return `tmux attach -t ${sessionName}`;