Session mission control

Run several Claude sessions at once — two VSCode windows, CLI + desktop, a mobile Remote Control session — and two problems appear: you can't see them all, and you waste attention hopping between windows to click "yes, continue." This runbook is the operator's guide to the two halves that solve that:

Read side — see every session: the /sessions command, a self-refreshing HTML dashboard, and a SwiftBar menu-bar plugin.
Attention side — get told which session needs you: the notify-attention hook, plus the permission allowlist that removes most prompts up front.

It builds directly on the write-side hooks from session safety — it reads the registry they already write and never mutates it.

The registry it reads

Each live session is one gitignored JSON file at <main-repo>/.claude/session/sessions/<session_id>.json, written by session-register (SessionStart), session-guard (each edit), and session-drift-check (each prompt). The directory is resolved via git --git-common-dir, so all of a repo's worktrees write into the main checkout's registry — a session in a /tmp worktree stays isolated for editing but is still visible here:

session_id, surface, cwd, repo_root, branch,
started_at / started_epoch, last_heartbeat / last_heartbeat_epoch,
baseline_head, baseline_origin_master, last_fetch_epoch,
files_touched: [...],
status: running | idle | waiting | ended,   # set by drift/stop/notify/end hooks
wait_state: { kind, reason, since_epoch },   # present only while blocked (kind = permission|input)
end_reason                                    # present only when ended

Status — is it stopped, and why?

The reader derives one state per session from status + wait_state + the heartbeat:

State	Meaning	Set by
running	actively working (mid-turn)	`session-drift-check` on each prompt
needs permission	stopped on a permission prompt — waiting on you	`notify-attention` (Notification event)
needs input	stopped on an idle prompt — waiting on you	`notify-attention` (Notification event)
idle	finished its turn, awaiting your next message	`session-stop` (Stop event)
ended	session closed (with reason: clear/logout/exit)	`session-end` (SessionEnd event)
stale	no heartbeat within the TTL	(heartbeat aged out)

Honest limits. Claude Code emits no distinct event for an Esc-interrupt or for "the whole task is complete" — both look identical to idle (the turn ended, awaiting you). So "idle" is "Claude stopped its turn and is waiting on you", whether it finished, was interrupted, or just paused. Everything else in the table is distinguishable.

session label — the view leads with the session's own title (Claude's generated aiTitle, e.g. "Close BeWith org-brain POC multi-workstream plan" — the same text VSCode shows), read live from the session transcript at ~/.claude/projects/<cwd-as-dashes>/<id>.jsonl. Falls back to the latest prompt, then the branch. This is far more useful than the branch, which is often just master or a worktree.
surface — where the session runs (vscode / cursor / cli / desktop / a terminal name), detected at SessionStart in priority order: an explicit CLAUDE_SURFACE → the CLAUDE_CODE_ENTRYPOINT → the macOS host-app bundle id (__CFBundleIdentifier) → TERM_PROGRAM. Claude Desktop sets no TERM_PROGRAM (it used to read unknown); it's now identified by its entrypoint / Anthropic bundle id — best-effort, since Desktop's exact env can't be verified from a VS Code/CLI session. Only a truly unrecognised launcher falls through to unknown.
live vs stale — live while the heartbeat is within SESSION_TTL_SECS (default 900s); it advances on SessionStart, every prompt, every edit, and on Stop — so a session in a long conversation stays live.
collision — two live (non-ended) sessions on the same branch+dir. session-guard blocks the later one; the view flags it so you see it coming.
reaping — stale/ended entries move to sessions/archive/ (never deleted; only paths, never content) on the next SessionStart.

Read side — seeing the sessions

`/sessions` (chat)

In any session, run /sessions. It invokes the sessions-view skill, which runs the reader and prints a table ordered by what needs you first: waiting → collisions → live → stale. Read-only.

HTML dashboard

A self-contained file:// dashboard, zero backend:

pnpm sessions             # = node scripts/sessions-view.mjs — writes + opens the HTML (macOS)
pnpm sessions --watch     # regenerates every 10s; the page auto-refreshes → a live wall display
node scripts/sessions-view.mjs --json       # machine-readable, what the skill consumes
node scripts/sessions-view.mjs --no-open    # write only, don't launch a browser

Leave a --watch terminal running and pin the browser tab for an always-on view.

Machine-wide view

The registry is per-main-repo (all of a repo's worktrees share it). By default the reader resolves the current repo's main checkout — run it from inside a worktree and it still finds the unified registry. To watch several repos at once, name each root:

node scripts/sessions-view.mjs --root /Users/you/workspace/repo-a --root /Users/you/workspace/repo-b
# or, once:
export SESSIONS_REGISTRY_ROOTS=/Users/you/workspace/repo-a:/Users/you/workspace/repo-b
pnpm sessions --watch

An always-present menu-bar icon (🟢 running / 🟠 collision / 🔴 someone needs you, + count — with your Claude usage % and Claude status folded in) with a dropdown table of every session, via a SwiftBar plugin. Optional — nobody is required to use it; it's a convenience over /sessions and the HTML dashboard. One command sets it all up (installs SwiftBar if missing, places the plugin, points SwiftBar at it, launches — no first-run folder picker to fight):

pnpm sessions:menubar        # = bash scripts/install-sessions-menubar.sh

It auto-discovers repos under ~/workspace/* (override with SESSIONS_REGISTRY_ROOTS or BEWITH_SESSIONS_GLOB). The 5s in the plugin filename = refresh every 5 seconds. The plugin is a thin wrapper over node scripts/sessions-view.mjs --swiftbar, so it shows exactly what /sessions shows. Wire it into the per-developer sandbox CLI by calling that script from install-developer.

Survives a reboot. Two layers start at login independently: the folded-in data feeds (the io.bewith.usage / io.bewith.status LaunchAgents) self-start via launchd RunAtLoad, and the installer registers SwiftBar itself as a Login Item so the icon comes back too. If after a reboot the icon is missing (e.g. the Login Item registration was denied the one-time Automation prompt), open it manually with open -a SwiftBar, or enable SwiftBar ▸ Preferences ▸ "Launch at Login". Re-running pnpm sessions:menubar re-registers everything idempotently.

Clicking a session focuses the VSCode window for that repo (open -a "Visual Studio Code" <repo>) — non-destructive, so a stray click does nothing harmful. The ▸ submenu has Re-attach in terminal (claude --resume), the cwd, and the wait reason.

What clicking can't do: focus the exact VSCode tab of that session. Claude Code exposes no "reveal session X" deep-link and the hook never receives a window handle, so the closest is "focus the repo's window" (above) or "re-attach in a terminal" (a new process). A signed standalone macOS menu-bar app wouldn't change this — it's a Claude Code surface-area limit, not a SwiftBar one. The standalone app is tracked as a deferred follow-up; it would read the same registry + --json contract.

What the dropdown can't do: render the HTML. SwiftBar menus are text (single-line items, no wrap/scroll), so the dropdown is an aligned text table; the full, wrapping, scrolling view is the HTML dashboard ("Open HTML dashboard" in the menu).

Attention side — being told who needs you

The notify-attention hook

Wired on the Claude Code Notification event (permission prompts + idle). On each notification, notify-attention.sh:

Writes wait_state into the session's registry entry → the read side shows ⏳ "waiting on me".
Pushes one alert through the first configured channel and falls back down the list: ntfy.sh topic → Slack webhook → macOS banner + bell. The message carries surface · branch · cwd · reason + claude --resume <session_id>.
Debounces per session+type (NOTIFY_DEBOUNCE_SECS, default 45s) so idle re-prompts don't spam you. wait_state is still refreshed.

Fail-open: any error → it does nothing and never blocks.

VSCode extension caveat. The Notification event does not fire inside the VSCode extension — permission prompts there surface as VSCode's own in-window toast, not as a hook. So notify-attention (the permission/idle push) only delivers in CLI sessions. In VSCode the Stop hook (session-stop.sh) is the only attention signal: it fires a turn-complete "your turn" banner when Claude finishes and you're looking at another window. "Another window" includes another VSCode tab you've since typed in — the gate suppresses only when your editor is frontmost and this is the tab you most recently prompted. (lsappinfo sees the frontmost app, not the tab, so it uses the most-recent prompt across live same-surface sessions as the proxy; it biases toward notifying when unsure.) Toggle with NOTIFY_TURN_COMPLETE (default on).

What stays an in-window toast only: a mid-turn permission prompt in VSCode. No hook fires for it, so it can't become an OS banner or a phone push — widen the allowlist (below) or use native Remote Control to view it on mobile.

Phone push & native mobile — two separate paths

To get alerts on your phone, there are two independent mechanisms:

ntfy / Slack — account-independent (ours). Set NTFY_TOPIC (or SLACK_WEBHOOK_URL) and the hooks push there; works on any phone regardless of which account it's logged into. notify-attention pushes the permission/idle alert, and the turn-complete "your turn" also pushes when NOTIFY_TURN_PUSH=true (off by default). Mint a personal, unguessable topic with scripts/sessions-notify-config.sh gen-topic (or ⚙️ menu → Generate my ntfy topic), then subscribe to the printed topic in the ntfy app. Treat the topic like a password.
- ntfy: zero account; the topic is the channel; a long random topic is your only privacy.
- Slack: each developer sets their own incoming-webhook URL (SLACK_WEBHOOK_URL) pointing at a private channel they own — a webhook is channel-bound and can't DM, so there's no shared-channel option here.
Claude native Remote Control / mobile push — account-coupled (built-in). /remote-control (or /rc) registers a session to claude.ai/code + the Claude mobile app; the /config toggle "Enable Remote Control for all sessions" makes it automatic for every session, and "Push when Claude decides" enables mobile pushes. Requires the same Claude account on desktop and phone — a different account on mobile receives nothing. You can view permission prompts on mobile but must approve them locally.

Easiest: the menu bar is the config screen. Open the SwiftBar dropdown → ⚙️ Settings:

Conversation language: English / Hebrew — the language Claude converses in (artifacts always stay English). Writes ~/.bewith/config.json via scripts/bewith-config.sh; same as /lang.
Role: dev / product + Default language — the capability-discovery role (/role) and the language fallback.
Claude usage % in menu bar — show the Claude account-usage percentage in the menu-bar title (show in menu bar) or only inside the dropdown (dropdown only). The usage section in the dropdown shows either way; this only controls the title suffix.
🖥 Open settings page — a read-only HTML view of every setting (value, source, and the command to change it).
Notifications: on/off — the master switch.
Local banner: auto / always / off — the macOS banner that pops top-right on this Mac (a local banner, as opposed to a remote ntfy/Slack push). auto = only when no remote channel fired; always = also alongside ntfy/Slack; off = never. If terminal-notifier is installed (the menu-bar installer adds it), the banner is clickable → it focuses the session's VSCode window; otherwise it's a plain non-clickable banner.
Notifier: NOTIFY_NOTIFIER — auto (default) uses terminal-notifier when installed (clickable + custom icon via NOTIFY_ICON/NOTIFY_CONTENT_IMAGE), else osascript. On macOS 26+ terminal-notifier needs notification permission (System Settings → Notifications → terminal-notifier → Allow) or it shows nothing yet exits 0; grant it — and set its Alert Style to Alerts so a "needs you" banner persists — or set NOTIFY_NOTIFIER=osascript.
Sound: on/off + a sound picker (Glass / Ping / Hero / Funk / Submarine).
🔔 Test notification — fires one now so you hear the current sound.
🎙 Custom sound — opens the config file; set NOTIFY_SOUND_FILE to a clip you recorded (Voice Memos / QuickTime → .aiff/.m4a/.wav), e.g. your own "i need you my master". A custom file is played with afplay and overrides the system sound.
Phone push on "your turn": on/off — also push the turn-complete alert to your phone via ntfy/Slack (needs a topic/webhook). Off by default (NOTIFY_TURN_PUSH).
🔑 Generate my ntfy topic — mints a per-dev NTFY_TOPIC (identity prefix + random suffix) and writes it; subscribe to the printed topic in the ntfy app.

These write the machine-level config at ~/.bewith/notify.env (managed by scripts/sessions-notify-config.sh), which applies to every session on the machine.

Configure it — by file (machine-level or per-repo)

Config is sourced machine-level first (~/.bewith/notify.env), then a per-repo override (<repo>/.claude/hooks/notify-attention.env, copy from the .example), then env vars. Gitignored — an ntfy topic / Slack webhook are secrets.

Var	Default	Meaning
`NOTIFY_ENABLED`	`true`	Master switch — any notification at all.
`NOTIFY_BANNER`	`auto`	Local macOS banner: `auto` (fallback only) / `always` / `off`. (Old name `NOTIFY_OSASCRIPT` still honored.)
`NOTIFY_SOUND`	`true`	Play a sound with the banner.
`NOTIFY_SOUND_NAME`	`Glass`	macOS system sound name.
`NOTIFY_SOUND_FILE`	(empty)	Custom audio file (`afplay`) — overrides the system sound; record your own.
`NTFY_TOPIC`	(empty)	ntfy topic → phone push. Mint one with `sessions-notify-config.sh gen-topic`.
`NTFY_SERVER` / `NTFY_PRIORITY`	`https://ntfy.sh` / `default`	Self-hosted server / priority (`high` cuts through DND).
`SLACK_WEBHOOK_URL`	(empty)	Your own per-dev incoming-webhook URL → its bound channel (no DMs).
`NOTIFY_TURN_COMPLETE`	`true`	The turn-complete "your turn" banner (the only VSCode attention signal).
`NOTIFY_TURN_PUSH`	`false`	Also push that "your turn" to ntfy/Slack, not just a local banner.
`NOTIFY_DEBOUNCE_SECS`	`45`	Suppress repeat pushes per session within this window.

With no config it still works: a local macOS banner + sound. Set a topic to also get it on your phone.

The hard limit — and why the allowlist matters more

A permission dialog cannot be approved from mobile or web Remote Control. (Verified against docs.claude.com.) Remote Control lets you view a session, type a follow-up, and continue — but a permission approval must happen where the session runs.

So the notification only tells you who needs you. What actually cuts the prompts is the permission allowlist:

This repo ships a curated, safe permissions.allow in .claude/settings.json; for consumer repos the same allowlist is opt-in — apply it (with a diff + confirmation) by running bewith platform permissions (user scope); bewith platform install no longer applies it automatically. Once applied, Claude Code merges allow-rules across scopes, so it covers every repo without a per-repo copy.
To also stop confirming every file edit, opt into edit-mode by adding "defaultMode": "acceptEdits" to your .claude/settings.json. It's opt-in, not the default, because it removes the per-edit pause.
For per-machine tuning from your real transcripts, the fewer-permission-prompts skill scans common calls and proposes additions.

Net: the allowlist removes ~most prompts, defaultMode: acceptEdits removes the edit pauses, and notify-attention centralizes the few that remain so you stop window-hopping to find them.

Consumer repos (plugin parity)

A repo that consumes the platform only through the bewith plugin gets all of this: .claude-plugin/hooks/hooks.json declares the session-safety set (session-register / session-guard / session-drift-check), the UserPromptSubmit event, and notify-attention — at parity with this repo's settings.json. (This closed a prior gap where the plugin omitted the session-safety hooks.) The reader and SwiftBar plugin work the same way against any repo's registry.

Verify it works

# Reader against the live registry
node scripts/sessions-view.mjs --json        # one row per session, with live/collision/wait_state
pnpm sessions                                 # opens the HTML dashboard

# Notification hook (writes wait_state, no real push)
SID=$(ls .claude/session/sessions/*.json | head -1 | xargs basename | sed 's/.json//')
printf '{"session_id":"%s","cwd":"%s","notification_type":"permission_prompt","message":"needs permission"}' "$SID" "$PWD" \
  | NOTIFY_OSASCRIPT=false bash .claude/hooks/notify-attention.sh
node scripts/sessions-view.mjs --json | grep -q wait_state && echo "wait_state set ✓"

A real end-to-end check: open two sessions on different branches → /sessions lists both; trigger a permission prompt → with NTFY_TOPIC set, a push arrives carrying the claude --resume hint; send a prompt to the waiting session → its ⏳ flag clears on the next view.

Session mission control

The registry it reads

Status — is it stopped, and why?

Read side — seeing the sessions

`/sessions` (chat)

HTML dashboard

Machine-wide view

Menu-bar app (most convenient) — optional

Attention side — being told who needs you

The notify-attention hook

Phone push & native mobile — two separate paths

Configure it — the ⚙️ Settings menu (no file editing)

Configure it — by file (machine-level or per-repo)

The hard limit — and why the allowlist matters more

Consumer repos (plugin parity)

Verify it works

See also

The registry it reads​

Status — is it stopped, and why?​

Read side — seeing the sessions​

/sessions (chat)​

HTML dashboard​

Machine-wide view​

Menu-bar app (most convenient) — optional​

Attention side — being told who needs you​

The notify-attention hook​

Phone push & native mobile — two separate paths​

Configure it — the ⚙️ Settings menu (no file editing)​

Configure it — by file (machine-level or per-repo)​

The hard limit — and why the allowlist matters more​

Consumer repos (plugin parity)​

Verify it works​

See also​

The registry it reads

Status — is it stopped, and why?

Read side — seeing the sessions

`/sessions` (chat)

HTML dashboard

Machine-wide view

Menu-bar app (most convenient) — optional

Attention side — being told who needs you

The notify-attention hook

Phone push & native mobile — two separate paths

Configure it — the ⚙️ Settings menu (no file editing)

Configure it — by file (machine-level or per-repo)

The hard limit — and why the allowlist matters more

Consumer repos (plugin parity)

Verify it works

See also