Handoff
Multi-instance Claude Code status indicator for tmux (+ persistent macOS alerts & jump-to switcher)
A tmux status-bar indicator that summarises every live Claude Code CLI instance at a glance plus macOS notifications that stay on screen until dismissed (and retract themselves once you look at the instance they came from), and an fzf popup to jump straight to any instances pane.
# Multi-instance Claude Code status indicator for tmux (+ persistent macOS alerts & jump-to switcher)
A tmux status-bar indicator that summarises **every live Claude Code CLI instance at a glance** plus macOS
notifications that **stay on screen until dismissed** (and retract themselves once you look at the
instance they came from), and an fzf popup to jump straight to any instance's pane. Built and
verified on **macOS 15.6 + Ghostty + tmux 3.6a + stock bash 3.2 + Claude Code CLI**; the core is
portable, the notification module is macOS-specific and called out as such.
---
## Quick reference
**The status bar** (`status-right`), e.g. `●2 👁3 ✋games ✅notes`:
| Element | Meaning |
| ----------------- | -------------------------------------------------- |
| `●N` (blue) | N instances **actively processing right now** |
| `👁M` (grey) | M instances **idle / already seen** |
| `✋name` (orange) | instance **blocked waiting for your approval** |
| `✅name` (green) | instance that **just finished**, not yet looked at |
| `· claude idle` | nothing running |
Counters lead so they survive truncation. `name` is the **tmux session name**. `✅` collapses into
`👁` once you focus that pane. More than 4 finished at once collapse to `✅+K`.
**Keys and commands**
| Action | How |
| -------------------------------- | --------------------------------------------------------- |
| Jump to any instance | `prefix + a` → fzf popup (live pane preview) → `Enter` |
| Dismiss one alert | Look at that instance's pane — it retracts itself |
| Dismiss all alerts for a session | Send it new work (`running` retracts), or end the session |
| Force a status-bar redraw | `tmux refresh-client -S` |
| Rebuild the notifier app | `~/.claude/hooks/claude-notifier-install.sh` |
**The day-to-day loop:** fire off work in several panes → tab away to a browser/editor → an alert
sits on screen per finished-or-blocked instance until you deal with it → open your terminal, look
at that pane, its alert disappears and its `✅` folds into `👁` → `prefix + a` to hop to the next.
**Where things live**
| Path | What |
| -------------------------------- | ------------------------------------------- |
| `~/.claude/hooks/*.sh` | all scripts |
| `~/.claude/status/<session-id>` | state file, `state\|epoch\|pane\|cwd` |
| `~/.claude/status/.viewed-<id>` | "you've looked at this" marker |
| `~/.claude/status/.notify-<id>` | "an alert is currently posted" marker |
| `~/.claude/bin/ClaudeNotify.app` | private notifier bundle (Module 7) |
| `~/.claude/settings.json` | hook wiring |
| `~/.tmux.conf` | status-right, focus hooks, switcher binding |
---
## What this is and why
People increasingly run **several Claude Code CLI sessions at once** — one per project, worktree,
or tmux pane. You lose track of them. Which are actively working? Which are blocked waiting for
you to approve a command? Which finished five minutes ago and are just sitting there? You end up
cycling through panes to check, and an agent that finished while you were in a browser can idle
for a long time before you notice.
This solves that with four things:
1. A **tmux status-bar indicator** summarising every live instance at a glance.
2. **macOS alerts** when an instance finishes or needs approval _while you're not looking at the
terminal_ — deliberately **manual-dismiss**, so they're still there when you come back.
3. **Automatic retraction** of an alert once you've actually seen that instance, so persistence
never turns into a pile of stale alerts to clear by hand.
4. A **popup switcher** to jump straight to any instance's pane.
The design point worth keeping: the status bar answers _"what's the state of everything?"_ at a
glance, and the alerts answer _"do I need to come back to the terminal at all?"_ when you're
elsewhere.
---
## For the implementing agent (read this first)
> **Default: build this as specified — then check in about variations.**
> The reader most likely saw this demonstrated and wants the same thing. Reproduce it as
> described. The defaults encode decisions arrived at by hitting the problems in _Known gotchas_ —
> treat them as load-bearing.
>
> **Do not open with "so which parts would you like?"** — that dumps design work on someone who
> just wants it working. Instead:
>
> 1. **State the plan and confirm it** — one question, phrased so "yes, all of it" is the easy
> answer. For example, verbatim: _"I'll install the full setup: the tmux status indicator for
> all your Claude instances, persistent macOS alerts that auto-dismiss once you view the
> instance, and a `prefix + a` popup switcher. Eight modules, roughly 15 minutes, and I'll
> verify each one as I go. Sound good?"_
> 2. **Interview only where their environment forces a decision** — not macOS (Module 6/7 are
> macOS-only as written), not tmux, a different terminal app (`TERMINAL_APP` must match their
> terminal's process name), `prefix + a` already bound, an existing `~/.claude/settings.json`
> with a `hooks` key to merge into, no `jq`/`fzf`. These are _compatibility_ questions, not
> preference questions. Don't silently substitute — ask, then adapt.
> 3. **Call out the genuinely optional pieces**, so opting out is cheap and informed: Module 5
> (viewed-collapse), Module 6+7 (notifications), Module 8 (switcher). Modules 1–4 are the core
> and only make sense together.
> 4. **Then invite variations** — and build them if asked. Don't propose a redesign unprompted.
>
> Deviate when the user asks or their environment requires it. Not because something looks
> tidier — that's how the gotchas get reintroduced.
The modules below are independently installable, so a user who wants only the status bar, or only
the notifications, can have exactly that — but that's their call to make, not your opening move.
---
## Known gotchas
**Load-bearing — don't simplify these away.** Each cost real debugging time.
| # | Symptom | Cause | Fix | Module |
| --- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 1 | `●` never lights up | "Working" is detected by grepping the pane's footer for `esc to interrupt`, a Claude TUI string, not a public API | Update `WORKING_MARK` at the top of `claude-tmux-status.sh` **and** `claude-switcher.sh` | 3, 8 |
| 2 | `✋`/`✅` never appear for a session | Hook config only applies to **newly started** Claude sessions | Restart the session. Discovery still lists old ones as `👁` — that's intended | 1 |
| 3 | Scripts fail with `declare -A` / substitution errors | macOS ships **bash 3.2** | Scripts avoid associative arrays and modern syntax on purpose; keep that if you edit them | all |
| 4 | Notifier call hangs the hook | `terminal-notifier`'s `-sender` / `-activate` flags can hang | Use only `-title/-message/-group` (and `-remove`) as shown | 6, 7 |
| 5 | Everything looks correctly configured but **no notification ever pops** | macOS suppresses **all** notifications — banners _and_ alerts — while the display is **mirrored or shared**, silently routing them to Notification Center. Costs hours if you record screencasts | System Settings → Notifications → **"Allow notifications when mirroring or sharing the display" = ON**. Diagnose with `system_profiler SPDisplaysDataType \| grep -i mirror` | 6, 7 |
| 6 | Editing Homebrew `terminal-notifier.app`'s `Info.plist` to `alert` changes nothing | macOS seeds an app's alert style from `NSUserNotificationAlertStyle` **only on that bundle id's first registration**. An already-registered app ignores it forever | Use a **copy with its own unused `CFBundleIdentifier`** (Module 7). This is the whole reason that module exists — not cosmetics | 7 |
| 7 | `-remove` silently does nothing | `NSUserNotificationCenter` only manages **its own app's** delivered notifications | The retract must run through the **same bundle that posted** — `ClaudeNotify.app`'s binary, not the Homebrew `terminal-notifier` on `PATH` | 7 |
| 8 | Notifier process spawns constantly / hooks feel sluggish | `running` fires on **every tool call**; an ungated retract launches a GUI binary each time | Gate every retract on `.notify-<id>` existing — it doubles as "an alert is currently posted" | 7 |
| 9 | Alerts pile up unread even after you've seen them | Manual-dismiss is the point, but nothing was retracting them | The retract hooks in Module 7 are not optional polish; without them persistence becomes a chore | 7 |
| 10 | Alert style silently reverts to Banners | Changing `BUNDLE_ID` later makes macOS treat it as a **brand-new app**, re-seeded and re-listed, with the old entry lingering in System Settings | Pick the id once and keep it. Re-running the installer with the same id is safe and preserves the style | 7 |
| 11 | Duplicated tmux hooks after every config reload | `set-hook -ga` **appends** | Use `set-hook -g` (plain) as shown | 5 |
| 12 | A Claude instance never appears | Discovery maps process TTY → tmux pane, so instances **outside tmux** are invisible, as are ones on another host or tmux server | Expected limitation; run Claude inside tmux | 2 |
| 13 | `prefix + a` does nothing / hits a plugin | Key already bound (e.g. `t-smart-tmux-session-manager` binds `T`) | Check `tmux list-keys -T prefix \| grep " a "` and pick a free key | 8 |
| 14 | Editing the `.app` "breaks its signature" | Homebrew's build is **ad-hoc, linker-signed, `Info.plist=not bound`** — editing `Info.plist` is safe and needs no re-sign | Confirm with `codesign -dv <app>`. If yours shows a real TeamIdentifier / sealed resources, re-sign after editing: `codesign --force --sign - <app>` | 7 |
| 15 | Status bar truncates | tmux `status-right-length` defaults to 40 | Set it to ~120 | 4 |
Two smaller ones: state markers are **dotfiles on purpose** (`.viewed-`/`.notify-`) so the
`"$dir"/*` glob that walks state files skips them; and this is **`~/.claude`-global**, monitoring
all your Claude sessions rather than one project.
---
## Dependencies at a glance
| Module | Hard dependencies | Alternatives / notes |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 1 — State tracking | Claude Code CLI, `jq`, bash | None; this is the foundation |
| 2 — Process discovery | `ps`, `awk`, `sort`, `grep`, tmux | `ps -Ao tty,command` works on macOS + Linux; adjust flags for an unusual `ps` (e.g. `-o tty,cmd`) |
| 3 — Renderer | Modules 1–2, tmux, `awk`, `grep` | — |
| 4 — tmux wiring | tmux (any modern version) | — |
| 5 — Viewed collapse | tmux with `focus-events on`, `set-hook` (tmux ≥ 3.0) | Skip it and finished instances stay `✅` until the session ends |
| 6 — Notifications | macOS; `terminal-notifier` **or** built-in `osascript`; AppleScript **Automation** permission for the terminal | Linux: swap `notify()` for `notify-send` and `user_is_looking()` for your WM's focus query (or always return false) |
| 7 — Persistent alerts | Module 6, `terminal-notifier` (**not** the `osascript` fallback), `plutil`, `lsregister` | macOS-only. Module 5 too, for view-triggered dismissal — see the module's note |
| 8 — Switcher | tmux ≥ 3.2 (`display-popup`), `fzf` | `tmux display-menu` (no fuzzy search, no preview) |
Author's baseline for reference: macOS 15.6, Ghostty 1.2.3 (quick-terminal/quake mode), tmux 3.6a,
fish as the interactive shell (irrelevant — every script is bash), Homebrew at `/opt/homebrew`.
Substitute freely; the only environment values that must match reality are `TERMINAL_APP` and any
absolute tool paths.
---
## The implementation
Create `~/.claude/hooks/` and `~/.claude/status/` if absent, and `chmod +x` every script.
Paths use `$HOME` throughout — every one of these runs through a shell (tmux `#(...)`,
`run-shell`, `display-popup -E`, Claude Code hook commands), so it expands. If a path fails to
resolve, substitute an absolute home directory and re-test.
### Module 1 — State tracking via Claude Code hooks (core)
On each Claude lifecycle event, write `~/.claude/status/<session-id>` = `state|epoch|pane|cwd`,
where state is `running` / `permission` / `done`; `clear` deletes it. Files: `claude-status.sh`
(below, shared with Modules 6–7) + the hooks block in `~/.claude/settings.json`.
### Module 2 — Process discovery (core)
Prints the tmux `pane_id` of every live `claude` process by matching process TTY to pane TTY.
**This is what makes idle instances appear at all** — a purely event-driven design misses them,
and shows a stuck "working" indicator after an ESC interrupt.
`~/.claude/hooks/claude-live-panes.sh`:
```bash
#!/usr/bin/env bash
# Outputs the tmux pane_id (one per line) of every live Claude Code CLI instance,
# by matching each `claude` process's TTY to a tmux pane's TTY. Authoritative and
# self-correcting: finds idle instances and ones with no state file.
# TTYs of live `claude` CLI processes. `$1 != "??"` drops the tty-less
# chrome-native-host helper; the basename check keeps only the real CLI.
ttys="$(ps -Ao tty,command 2>/dev/null | awk '
$1 != "??" {
n = split($2, p, "/")
if (p[n] == "claude") print $1
}
' | sort -u)"
[ -n "$ttys" ] || exit 0
# Emit the pane whose tty matches each claude tty (pane_tty is /dev/ttysNNN).
tmux list-panes -a -F '#{pane_tty} #{pane_id}' 2>/dev/null | while read -r ptty pid; do
printf '%s\n' "$ttys" | grep -qxF "${ptty#/dev/}" && printf '%s\n' "$pid"
done
```
### Module 3 — Status-line renderer (core)
For each discovered pane: footer says working → `●`; otherwise overlay the newest state file for
that pane. Three signals, each used for what it's best at — **which instances exist** comes from
process discovery, **is it working right now** from the pane's own footer (never stuck, unlike an
event flag after an interrupt), **everything else** from hook state files.
`~/.claude/hooks/claude-tmux-status.sh`:
```bash
#!/usr/bin/env bash
# Prints the one-line Claude status summary for tmux status-right.
# 1. Which instances exist -> claude-live-panes.sh (TTY -> pane).
# 2. Is it working right now -> the pane footer shows "esc to interrupt".
# 3. Other states -> hook state files ~/.claude/status/<sid>.
# Layout: ●N 👁M ✋<perm names> ✅<done names, cap then ✅+K> (counters lead).
# Written for macOS's stock bash 3.2.
dir="$HOME/.claude/status"
panes_helper="$HOME/.claude/hooks/claude-live-panes.sh"
DONE_CAP=4
WORKING_MARK='esc to interrupt' # Claude's footer shows this only while processing
live_panes=" $(tmux list-panes -a -F '#{pane_id}' 2>/dev/null | tr '\n' ' ') "
# Load state files into arrays; prune files whose pane is truly gone.
n=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r st ts pn cw < "$f"
sid="$(basename "$f")"
if [ -n "$pn" ]; then
case "$live_panes" in
*" $pn "*) : ;;
*) rm -f "$f" "$dir/.viewed-$sid" "$dir/.notify-$sid"; continue ;;
esac
fi
A_STATE[$n]="$st"; A_TS[$n]="${ts:-0}"; A_PANE[$n]="$pn"; A_SID[$n]="$sid"
n=$((n + 1))
done
running=0; viewed=0; done_count=0; perm_l=""; done_l=""
pane_working() { # 0 (true) if the pane's footer shows Claude is processing
tmux capture-pane -p -t "$1" 2>/dev/null | awk 'NF{l=$0} END{print l}' | grep -q "$WORKING_MARK"
}
classify_idle() { # state sid label -- for a pane that is NOT actively working
local state="$1" sid="$2" label="$3"
case "$state" in
permission) perm_l="$perm_l #[fg=colour208,bold]✋${label}#[default]" ;;
done)
if [ -n "$sid" ] && [ -f "$dir/.viewed-$sid" ]; then
viewed=$((viewed + 1))
else
done_count=$((done_count + 1))
[ "$done_count" -le "$DONE_CAP" ] && done_l="$done_l #[fg=colour46,bold]✅${label}#[default]"
fi ;;
*) viewed=$((viewed + 1)) ;; # idle / stuck-running / waiting / untracked
esac
}
for pane in $(bash "$panes_helper" 2>/dev/null); do
label="$(tmux display-message -p -t "$pane" '#{session_name}' 2>/dev/null)"
[ -n "$label" ] || label="claude"
if pane_working "$pane"; then
running=$((running + 1)); continue
fi
bi=-1; bts=-1; k=0
while [ "$k" -lt "$n" ]; do
if [ "${A_PANE[$k]}" = "$pane" ] && [ "${A_TS[$k]}" -gt "$bts" ]; then bts="${A_TS[$k]}"; bi="$k"; fi
k=$((k + 1))
done
if [ "$bi" -ge 0 ]; then classify_idle "${A_STATE[$bi]}" "${A_SID[$bi]}" "$label"
else classify_idle "idle" "" "$label"; fi
done
if [ "$done_count" -gt "$DONE_CAP" ]; then
done_l="$done_l #[fg=colour46,bold]✅+$((done_count - DONE_CAP))#[default]"
fi
out=""
[ "$running" -gt 0 ] && out="$out #[fg=colour39]●${running}#[default]"
[ "$viewed" -gt 0 ] && out="$out #[fg=colour244]👁${viewed}#[default]"
out="$out$perm_l$done_l"
if [ -n "$out" ]; then printf '%s' "${out# }"
else printf '#[fg=colour240]· claude idle#[default]'; fi
```
### Module 4 — tmux wiring (core)
See the `~/.tmux.conf` block at the end of this section; Module 4 is the first two lines.
### Module 5 — "Viewed" collapse (optional)
When you **focus** a finished instance's pane, drop a `.viewed-<id>` marker so `✅name` collapses
into the `👁` count — gated on real focus, so an instance finishing while your terminal is
backgrounded stays a visible `✅`. The same hook retracts that instance's alert (Module 7).
Skipping this: also drop the five `set-hook` lines from `~/.tmux.conf`, and Module 7 loses
view-triggered dismissal (it still retracts on `running`/`clear`).
`~/.claude/hooks/claude-mark-viewed.sh`:
```bash
#!/usr/bin/env bash
# Marks finished ('done') Claude sessions as "viewed" once you actually focus
# their pane, so they collapse from the named list into the 👁 counter.
#
# Invoked (backgrounded) by tmux focus/navigation hooks in ~/.tmux.conf:
# after-select-pane, after-select-window, client-session-changed,
# client-attached, client-focus-in.
# Using client-focus-in means "viewed" only counts when the terminal itself
# has OS focus -- a task finishing while the terminal is backgrounded is NOT hidden.
dir="$HOME/.claude/status"
[ -d "$dir" ] || exit 0
# Focused pane(s): the active pane of the active window of each attached session.
focused=" $(tmux list-panes -a \
-f '#{&&:#{pane_active},#{&&:#{window_active},#{session_attached}}}' \
-F '#{pane_id}' 2>/dev/null | tr '\n' ' ') "
changed=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r state ts pane cwd < "$f"
[ -n "$pane" ] || continue
case "$focused" in *" $pane "*) ;; *) continue ;; esac
sid="$(basename "$f")"
[ "$state" = "done" ] && { marker="$dir/.viewed-$sid"; [ -f "$marker" ] || { touch "$marker"; changed=1; }; }
# --- Module 7: looking at the pane means you've seen it, so retract its macOS alert.
# Those are manual-dismiss and would otherwise pile up until clicked. .notify-<sid>
# doubles as "an alert is currently posted", so this fires once and only when there's
# one to pull down. Applies to `permission` too: the ✋ in the bar is the standing
# reminder. Delete this block if you skip Module 7.
if [ -f "$dir/.notify-$sid" ]; then
"$HOME/.claude/hooks/claude-notify-clear.sh" "$sid"
rm -f "$dir/.notify-$sid"
fi
done
# Only force a redraw when something actually changed.
[ "$changed" -eq 1 ] && tmux refresh-client -S 2>/dev/null
exit 0
```
### Module 6 — Desktop notifications (optional, macOS as written)
Notify on `permission`/`done` **only when the terminal isn't frontmost** (so you're never spammed
while watching), de-duplicated per session, silent. Lives inside `claude-status.sh` below.
### Module 7 — Persistent alerts that retract themselves (optional, macOS)
**The problem it solves:** a banner auto-fades after a few seconds. If you're away from the desk
when an agent finishes, you miss it entirely and the whole notification is wasted. macOS's
**Alerts** style stays on screen until dismissed — but alert style is a **per-app OS setting**,
not something a notification payload can request.
**Why a private app bundle:** macOS seeds an app's style from `NSUserNotificationAlertStyle` in
its `Info.plist`, but **only the first time that bundle id registers**. Homebrew's
`terminal-notifier` is long since registered as `banner`, so editing its plist does nothing — and
flipping its style by hand in System Settings would make _every_ script that uses it persistent.
So: a copy of the bundle with its own `CFBundleIdentifier`. It also makes notifications read as
**"Claude Code"** rather than "terminal-notifier".
**Why it auto-retracts:** persistence without retraction just moves the chore. Every alert is
tagged `-group claude-<session-id>`, which is a precise handle to pull that one back down, from
three places: you focused that instance's pane (Module 5), work resumed, or the session ended.
Only the _focused_ instance's alert is retracted — the others keep standing, which is the point.
`~/.claude/hooks/claude-notifier-install.sh` — run once (and again after
`brew upgrade terminal-notifier`):
```bash
#!/usr/bin/env bash
# (Re)builds ~/.claude/bin/ClaudeNotify.app -- a private copy of terminal-notifier.app used
# by claude-status.sh to post macOS notifications that DO NOT auto-dismiss.
#
# Why a copy: macOS alert style is per-app, and an app's *initial* style is seeded from
# NSUserNotificationAlertStyle in its Info.plist the first time it registers. Homebrew's
# terminal-notifier ships "banner" and is already registered, so the only way to get
# persistent Alerts without hijacking every other terminal-notifier caller is a bundle with
# its own CFBundleIdentifier. Bonus: notifications are attributed to "Claude Code".
#
# Run again after `brew upgrade terminal-notifier` to pick up the new binary. The bundle id
# stays the same, so the alert style already chosen in System Settings is preserved.
set -euo pipefail
# Any reverse-DNS id you have NEVER used before -- the unused-ness is what makes the style
# seeding work. Put your own name/domain in it. Don't change it later (see gotcha 10).
BUNDLE_ID="com.example.claude-notify"
BUNDLE_NAME="Claude Code"
DST="$HOME/.claude/bin/ClaudeNotify.app"
src_bin="$(command -v terminal-notifier || true)"
[ -n "$src_bin" ] || { echo "terminal-notifier not found -- brew install terminal-notifier" >&2; exit 1; }
# Locate terminal-notifier.app. Homebrew's bin/terminal-notifier is a two-line wrapper that
# execs the binary inside the bundle, so read the path straight out of it; other install
# layouts put the CLI inside the bundle itself, so fall back to resolving the symlink.
SRC="$(sed -n 's|.*"\(/.*\.app\)/Contents/MacOS/[^"]*".*|\1|p' "$src_bin" 2>/dev/null | head -1)"
if [ ! -d "${SRC:-}" ]; then
real="$(readlink -f "$src_bin" 2>/dev/null || python3 -c 'import os,sys;print(os.path.realpath(sys.argv[1]))' "$src_bin")"
case "$real" in */Contents/MacOS/*) SRC="${real%/Contents/MacOS/*}" ;; esac
fi
[ -d "${SRC:-}" ] || { echo "could not locate terminal-notifier.app (from $src_bin)" >&2; exit 1; }
mkdir -p "$(dirname "$DST")"
rm -rf "$DST"
cp -R "$SRC" "$DST"
plist="$DST/Contents/Info.plist"
plutil -replace CFBundleIdentifier -string "$BUNDLE_ID" "$plist"
plutil -replace CFBundleName -string "$BUNDLE_NAME" "$plist"
plutil -replace NSUserNotificationAlertStyle -string "alert" "$plist"
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f "$DST"
echo "built $DST ($BUNDLE_ID)"
echo "verify: System Settings > Notifications > \"$BUNDLE_NAME\" -> Alert style = Alerts"
"$DST/Contents/MacOS/terminal-notifier" -title "Claude Code" -message "Persistent alert test -- this should stay until dismissed" -group claude-install-test
```
`~/.claude/hooks/claude-notify-clear.sh`:
```bash
#!/usr/bin/env bash
# Pulls down the macOS alert(s) that claude-status.sh posted for the given session id(s).
# Usage: claude-notify-clear.sh <session-id> [session-id...]
#
# The alerts are manual-dismiss by design (see claude-notifier-install.sh), so something has
# to retract them once they're moot. Callers:
# * claude-mark-viewed.sh -- you focused that instance's pane, so you've seen it
# * claude-status.sh -- the session went `running` again, or ended (`clear`)
#
# NSUserNotificationCenter only manages its own app's delivered notifications, so the remove
# MUST go through the same bundle that posted -- hence the ClaudeNotify.app path first, with
# the same fallback order as claude-status.sh's notify().
set -u
bin="$HOME/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier"
[ -x "$bin" ] || bin="$(command -v terminal-notifier 2>/dev/null || true)"
[ -n "$bin" ] || exit 0
for sid in "$@"; do
[ -n "$sid" ] || continue
"$bin" -remove "claude-$sid" >/dev/null 2>&1 || true
done
exit 0
```
**One manual step, once:** after the installer's test notification appears, open
**System Settings → Notifications → "Claude Code"** and confirm **Alert style = Alerts**. The
`Info.plist` seeding normally sets it; the dropdown is the ground truth, and one click fixes it
permanently if it reads Banners.
### Modules 1 + 6 + 7 — `~/.claude/hooks/claude-status.sh`
The shared entry point. Module boundaries are marked; delete a marked block to skip that module.
```bash
#!/usr/bin/env bash
# Records this Claude session's status for the tmux indicator, and fires a
# macOS notification when the session goes idle while the terminal is not the
# frontmost app (closed or tabbed away from).
# Usage: claude-status.sh <running|permission|done|clear>
# Hook JSON (with .session_id and .cwd) is read from stdin.
state="${1:-}"
dir="$HOME/.claude/status"
mkdir -p "$dir"
input="$(cat)"
sid="$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)"
[ -n "$sid" ] || sid="unknown"
file="$dir/$sid"
notif_marker="$dir/.notify-$sid"
viewed_marker="$dir/.viewed-$sid"
cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
# --- Module 7: an alert from the last idle may still be on screen (they're manual-dismiss).
# Work resuming or the session ending makes it moot, so retract it. Gated on the marker
# existing, since `running` fires on every tool call and must not spawn the notifier each
# time. Delete this block if you skip Module 7.
case "$state" in
running|clear)
[ -f "$notif_marker" ] && "$HOME/.claude/hooks/claude-notify-clear.sh" "$sid"
;;
esac
# --- write / clear state for the tmux status bar (Module 1) ---
if [ "$state" = "clear" ]; then
rm -f "$file" "$notif_marker" "$viewed_marker"
else
# state | epoch | tmux pane (empty when not in tmux) | cwd -- written atomically
# so the renderer / mark-viewed hook never see a half-written line.
printf '%s|%s|%s|%s\n' "$state" "$(date +%s)" "${TMUX_PANE:-}" "$cwd" > "$file.tmp" \
&& mv -f "$file.tmp" "$file"
fi
# New work resumes: reset the notify marker (so the next idle notifies again) and
# drop the viewed marker (a fresh cycle should re-show, not stay collapsed).
[ "$state" = "running" ] && rm -f "$notif_marker" "$viewed_marker"
# ============ Module 6 (+7): notify when idle and you're not looking ============
TERMINAL_APP="ghostty" # System Events process name of YOUR terminal (case-insensitive)
# Module 7's private bundle: same terminal-notifier binary, but its own CFBundleIdentifier
# and NSUserNotificationAlertStyle=alert, so what it posts stays on screen until dismissed.
# Falls back to plain terminal-notifier (banners) if Module 7 isn't installed.
NOTIFIER_BIN="$HOME/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier"
notify() {
local title="$1" msg="$2" bin="$NOTIFIER_BIN"
[ -x "$bin" ] || bin="$(command -v terminal-notifier 2>/dev/null || true)"
if [ -n "$bin" ]; then
# Plain, non-blocking, silent. -sender/-activate can hang; don't add them.
# For it to actually POP (not just land in Notification Center):
# 1. alert style is Banners or Alerts, not None (System Settings > Notifications)
# 2. "Allow notifications when mirroring or sharing the display" = ON
# -- macOS hides ALL notifications while the screen is mirrored/recorded otherwise.
# -group is also the handle claude-notify-clear.sh uses to pull the alert back down.
"$bin" -title "$title" -message "$msg" -group "claude-$sid" >/dev/null 2>&1 || true
else
local t="${title//\\/\\\\}"; t="${t//\"/\\\"}"
local m="${msg//\\/\\\\}"; m="${m//\"/\\\"}"
osascript -e "display notification \"$m\" with title \"$t\"" 2>/dev/null || true
fi
}
# Returns 0 when you ARE looking at the terminal (it's frontmost) -> suppress notify.
user_is_looking() {
local front
front="$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null)"
if [ -n "$front" ]; then
[ "$(printf '%s' "$front" | tr '[:upper:]' '[:lower:]')" = "$(printf '%s' "$TERMINAL_APP" | tr '[:upper:]' '[:lower:]')" ]
return
fi
# Frontmost unknown (e.g. Automation permission denied) -> fall back to tmux clients.
if [ -n "$TMUX" ]; then
local clients; clients="$(tmux list-clients 2>/dev/null | wc -l | tr -d ' ')"
[ "${clients:-0}" -gt 0 ]; return
fi
return 1
}
case "$state" in
done|permission)
# Notify only when you're NOT looking at the terminal, and dedupe on state change.
last="$(cat "$notif_marker" 2>/dev/null || true)"
if ! user_is_looking && [ "$state" != "$last" ]; then
proj="$(basename "$cwd" 2>/dev/null)"
[ -n "$proj" ] && [ "$proj" != "." ] || proj="claude"
if [ "$state" = "permission" ]; then
notify "Claude · needs approval" "✋ $proj needs your approval"
else
notify "Claude · done" "✅ $proj finished — your turn"
fi
printf '%s' "$state" > "$notif_marker"
fi
;;
esac
# ====================== end Modules 6/7 ======================
# Redraw the tmux status bar immediately (server-wide, best-effort).
tmux refresh-client -S 2>/dev/null || true
exit 0
```
### Module 8 — Jump-to switcher popup (optional)
`prefix + a` → fzf popup of every instance (state emoji, `session:window.pane`, project, age)
with a live preview of that pane; `Enter` jumps to it.
`~/.claude/hooks/claude-switcher.sh`:
```bash
#!/usr/bin/env bash
# fzf popup listing every live Claude instance; Enter jumps to its pane.
# Bound to `prefix + a` via display-popup.
dir="$HOME/.claude/status"
panes_helper="$HOME/.claude/hooks/claude-live-panes.sh"
WORKING_MARK='esc to interrupt'
FZF=fzf
command -v fzf >/dev/null 2>&1 || FZF=/opt/homebrew/bin/fzf # fallback path; adjust if needed
now="$(date +%s)"
n=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r st ts pn cw < "$f"
A_STATE[$n]="$st"; A_TS[$n]="${ts:-0}"; A_PANE[$n]="$pn"; A_CWD[$n]="$cw"; A_SID[$n]="$(basename "$f")"
n=$((n + 1))
done
pane_working() { tmux capture-pane -p -t "$1" 2>/dev/null | awk 'NF{l=$0} END{print l}' | grep -q "$WORKING_MARK"; }
rows=""
for pane in $(bash "$panes_helper" 2>/dev/null); do
bi=-1; bts=-1; k=0
while [ "$k" -lt "$n" ]; do
if [ "${A_PANE[$k]}" = "$pane" ] && [ "${A_TS[$k]}" -gt "$bts" ]; then bts="${A_TS[$k]}"; bi="$k"; fi
k=$((k + 1))
done
if [ "$bi" -ge 0 ]; then st="${A_STATE[$bi]}"; ts="${A_TS[$bi]}"; cwd="${A_CWD[$bi]}"; sid="${A_SID[$bi]}"
else st="idle"; ts=0; cwd=""; sid=""; fi
if pane_working "$pane"; then
emoji="●"; status="working"
else
case "$st" in
permission) emoji="✋"; status="needs approval" ;;
done) if [ -n "$sid" ] && [ -f "$dir/.viewed-$sid" ]; then emoji="👁"; status="idle"; else emoji="✅"; status="done"; fi ;;
*) emoji="👁"; status="idle" ;;
esac
fi
loc="$(tmux display-message -p -t "$pane" '#{session_name}:#{window_index}.#{pane_index}' 2>/dev/null)"
[ -n "$loc" ] || loc="$pane"
if [ -n "$cwd" ]; then proj="$(basename "$cwd")"
else proj="$(basename "$(tmux display-message -p -t "$pane" '#{pane_current_path}' 2>/dev/null)")"; fi
[ -n "$proj" ] && [ "$proj" != "." ] || proj="—"
if [ "$status" != "working" ] && [ "$ts" -gt 0 ]; then
age=$(( now - ts ))
if [ "$age" -lt 60 ]; then when="${age}s ago"
elif [ "$age" -lt 3600 ]; then when="$((age / 60))m ago"
else when="$((age / 3600))h ago"; fi
else when="$status"; fi
rows="$rows${pane}"$'\t'"$emoji $loc $proj $when"$'\n'
done
if [ -z "$rows" ]; then printf 'No Claude instances.\n'; sleep 1; exit 0; fi
sel="$(printf '%s' "$rows" | "$FZF" \
--ansi --delimiter='\t' --with-nth=2.. --prompt='claude ▸ ' \
--preview 'tmux capture-pane -pe -J -t {1}' --preview-window=right:60%)"
[ -n "$sel" ] || exit 0
pane="$(printf '%s' "$sel" | cut -f1)"
[ -n "$pane" ] || exit 0
sess="$(tmux display-message -p -t "$pane" '#{session_name}' 2>/dev/null)"
tmux switch-client -t "$sess" \; select-window -t "$pane" \; select-pane -t "$pane"
```
### `~/.claude/settings.json` — hooks block (merge into any existing file)
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh permission"
}
]
},
{
"matcher": "idle_prompt",
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh done"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh done"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh clear"
}
]
}
]
}
}
```
- **`PostToolUse → running` matters:** `PreToolUse` fires _before_ a permission prompt, so
`PostToolUse` is what clears the `permission` state after you approve.
- **The `Notification` matcher split** is the reliable way to distinguish a permission prompt from
an idle "your turn" — do **not** regex the notification message text. `matcher` goes on the
group object, exactly as shown.
### `~/.tmux.conf` — additions
```tmux
# --- Claude status indicator (Module 4) ---
set -g status-right "#($HOME/.claude/hooks/claude-tmux-status.sh)"
set -g status-right-length 120 # default 40 truncates once several sessions are open
# Module 5: collapse a finished instance into 👁 once you focus its pane (and retract its
# alert, Module 7). focus-events must be on for client-focus-in to fire.
set -g focus-events on
set-hook -g after-select-pane 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g after-select-window 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-session-changed 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-attached 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-focus-in 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
# Module 8: popup switcher (pick a key that's free for you; verify prefix+a is unbound).
bind-key a display-popup -E -w 80% -h 60% "$HOME/.claude/hooks/claude-switcher.sh"
```
Reload with `tmux source-file ~/.tmux.conf`. Use plain `set-hook -g` (not `-ga`) so reloading
doesn't stack duplicate hooks; these hook names are unset by default and unused by common plugins.
---
## Install order
**Install all of it unless the user said otherwise.** Foundation first, so there's something
visible to demo at every step.
1. `mkdir -p ~/.claude/hooks ~/.claude/status` — and `chmod +x ~/.claude/hooks/*.sh` as you go.
2. **Modules 1–4 (core).** `claude-status.sh` (you can paste the full version now; Modules 6/7's
blocks are inert until their scripts exist), `claude-live-panes.sh`,
`claude-tmux-status.sh`, the settings.json hooks, the first two `~/.tmux.conf` lines.
Reload tmux, **start a fresh Claude session** (gotcha 2) — the bar should light up. _Demoable._
3. **Module 5** — `claude-mark-viewed.sh` + the five `set-hook` lines. _Demoable: `✅` → `👁`._
4. **Module 6** — set `TERMINAL_APP`; grant the terminal **Automation** permission for System
Events on first prompt; on macOS enable _Allow notifications when mirroring or sharing the
display_ (gotcha 5). _Demoable: tab away, wait for a task to finish._
5. **Module 7** — `brew install terminal-notifier`, add `claude-notify-clear.sh`, set `BUNDLE_ID`
in `claude-notifier-install.sh`, run it, then confirm the alert style in System Settings.
_Demoable: an alert that outlives a banner and vanishes when you look at its pane._
6. **Module 8** — `claude-switcher.sh` + the `bind-key`; confirm the key is free first.
---
## Verification quick-checks
| Run this | Expect |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `bash ~/.claude/hooks/claude-live-panes.sh` | one pane id per live Claude instance. Cross-check: `tmux list-panes -a -F '#{pane_id} #{session_name}'` |
| `~/.claude/hooks/claude-tmux-status.sh \| sed -E 's/#\[[^]]*\]//g'` | the rendered line, colours stripped, e.g. `●1 👁2` |
| Start a task in a Claude pane | `●` appears for it; on finish it becomes `✅<session>` |
| Trigger a tool needing approval (in a **fresh** session) | `✋<session>`; approve → `●` → `✅` |
| Focus a `✅` instance's pane | it folds into the `👁` count |
| `prefix + a` | popup lists every instance with a live preview; `Enter` jumps there |
| Tab away from the terminal, let a task finish | one notification, titled **Claude Code** |
| `~/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier -list ALL` | a row per still-posted alert, with group `claude-<session-id>` |
| Leave an alert for 30s without touching it | still on screen — that's Alerts style working (a banner would be long gone) |
| Now focus that instance's pane | alert disappears on its own; `-list ALL` no longer shows it |
| `defaults read ~/.claude/bin/ClaudeNotify.app/Contents/Info.plist NSUserNotificationAlertStyle` | `alert` |
**How the known failure modes present:**
- **No notification at all, everything else fine** → mirroring (gotcha 5) first, then Focus mode,
then alert style set to _None_ in System Settings.
- **Notification appears but fades in ~5s** → the bundle's style is Banners, not Alerts: check the
System Settings dropdown for "Claude Code" (gotcha 6). Confirm you're posting through
`ClaudeNotify.app`, not the Homebrew `terminal-notifier` on `PATH`.
- **Alerts appear but never retract** → `-remove` going through the wrong bundle (gotcha 7), or a
stale/missing `.notify-<id>` marker (`ls -a ~/.claude/status/`).
- **`●` never appears, other states fine** → the footer string changed (gotcha 1).
- **`✋`/`✅` never appear for one session** → it predates the hook config (gotcha 2).
---
## Optional extensions
- **Emojis/colours:** the glyphs and `#[fg=colourNNN]` codes in `claude-tmux-status.sh` /
`claude-switcher.sh` (tmux 256-colour palette). `DONE_CAP` controls how many `✅` names show
before collapsing to `✅+K`.
- **Name idle instances too:** move that case out of the `*)` count in `classify_idle`.
- **Click-to-jump alerts:** `terminal-notifier -execute '<command>'` runs a shell command when the
alert is clicked, so a click could switch tmux to the pane that raised it. Worth knowing if you
use a quake/dropdown terminal: `open -a <Terminal>` only activates the app and can't summon a
dropdown window — Ghostty 1.2.3 exposes a `QuickTerminalIntent` App Intent ("Open the Quick
Terminal… if already open, do nothing") reachable from a one-action Shortcut via
`shortcuts run "<name>"`; there is no CLI equivalent (`ghostty +new-window` is GTK/D-Bus,
Linux-only). Deliberately **not** installed here — auto-retract on view proved cleaner than
making the alert something you must click.
- **No tmux?** Modules 1, 6 and 7 work standalone; build a different front-end (menu-bar app,
notification-only setup) on top of the `~/.claude/status/` files.
# Multi-instance Claude Code status indicator for tmux (+ persistent macOS alerts & jump-to switcher)
A tmux status-bar indicator that summarises **every live Claude Code CLI instance at a glance** plus macOS
notifications that **stay on screen until dismissed** (and retract themselves once you look at the
instance they came from), and an fzf popup to jump straight to any instance's pane. Built and
verified on **macOS 15.6 + Ghostty + tmux 3.6a + stock bash 3.2 + Claude Code CLI**; the core is
portable, the notification module is macOS-specific and called out as such.
---
## Quick reference
**The status bar** (`status-right`), e.g. `●2 👁3 ✋games ✅notes`:
| Element | Meaning |
| ----------------- | -------------------------------------------------- |
| `●N` (blue) | N instances **actively processing right now** |
| `👁M` (grey) | M instances **idle / already seen** |
| `✋name` (orange) | instance **blocked waiting for your approval** |
| `✅name` (green) | instance that **just finished**, not yet looked at |
| `· claude idle` | nothing running |
Counters lead so they survive truncation. `name` is the **tmux session name**. `✅` collapses into
`👁` once you focus that pane. More than 4 finished at once collapse to `✅+K`.
**Keys and commands**
| Action | How |
| -------------------------------- | --------------------------------------------------------- |
| Jump to any instance | `prefix + a` → fzf popup (live pane preview) → `Enter` |
| Dismiss one alert | Look at that instance's pane — it retracts itself |
| Dismiss all alerts for a session | Send it new work (`running` retracts), or end the session |
| Force a status-bar redraw | `tmux refresh-client -S` |
| Rebuild the notifier app | `~/.claude/hooks/claude-notifier-install.sh` |
**The day-to-day loop:** fire off work in several panes → tab away to a browser/editor → an alert
sits on screen per finished-or-blocked instance until you deal with it → open your terminal, look
at that pane, its alert disappears and its `✅` folds into `👁` → `prefix + a` to hop to the next.
**Where things live**
| Path | What |
| -------------------------------- | ------------------------------------------- |
| `~/.claude/hooks/*.sh` | all scripts |
| `~/.claude/status/<session-id>` | state file, `state\|epoch\|pane\|cwd` |
| `~/.claude/status/.viewed-<id>` | "you've looked at this" marker |
| `~/.claude/status/.notify-<id>` | "an alert is currently posted" marker |
| `~/.claude/bin/ClaudeNotify.app` | private notifier bundle (Module 7) |
| `~/.claude/settings.json` | hook wiring |
| `~/.tmux.conf` | status-right, focus hooks, switcher binding |
---
## What this is and why
People increasingly run **several Claude Code CLI sessions at once** — one per project, worktree,
or tmux pane. You lose track of them. Which are actively working? Which are blocked waiting for
you to approve a command? Which finished five minutes ago and are just sitting there? You end up
cycling through panes to check, and an agent that finished while you were in a browser can idle
for a long time before you notice.
This solves that with four things:
1. A **tmux status-bar indicator** summarising every live instance at a glance.
2. **macOS alerts** when an instance finishes or needs approval _while you're not looking at the
terminal_ — deliberately **manual-dismiss**, so they're still there when you come back.
3. **Automatic retraction** of an alert once you've actually seen that instance, so persistence
never turns into a pile of stale alerts to clear by hand.
4. A **popup switcher** to jump straight to any instance's pane.
The design point worth keeping: the status bar answers _"what's the state of everything?"_ at a
glance, and the alerts answer _"do I need to come back to the terminal at all?"_ when you're
elsewhere.
---
## For the implementing agent (read this first)
> **Default: build this as specified — then check in about variations.**
> The reader most likely saw this demonstrated and wants the same thing. Reproduce it as
> described. The defaults encode decisions arrived at by hitting the problems in _Known gotchas_ —
> treat them as load-bearing.
>
> **Do not open with "so which parts would you like?"** — that dumps design work on someone who
> just wants it working. Instead:
>
> 1. **State the plan and confirm it** — one question, phrased so "yes, all of it" is the easy
> answer. For example, verbatim: _"I'll install the full setup: the tmux status indicator for
> all your Claude instances, persistent macOS alerts that auto-dismiss once you view the
> instance, and a `prefix + a` popup switcher. Eight modules, roughly 15 minutes, and I'll
> verify each one as I go. Sound good?"_
> 2. **Interview only where their environment forces a decision** — not macOS (Module 6/7 are
> macOS-only as written), not tmux, a different terminal app (`TERMINAL_APP` must match their
> terminal's process name), `prefix + a` already bound, an existing `~/.claude/settings.json`
> with a `hooks` key to merge into, no `jq`/`fzf`. These are _compatibility_ questions, not
> preference questions. Don't silently substitute — ask, then adapt.
> 3. **Call out the genuinely optional pieces**, so opting out is cheap and informed: Module 5
> (viewed-collapse), Module 6+7 (notifications), Module 8 (switcher). Modules 1–4 are the core
> and only make sense together.
> 4. **Then invite variations** — and build them if asked. Don't propose a redesign unprompted.
>
> Deviate when the user asks or their environment requires it. Not because something looks
> tidier — that's how the gotchas get reintroduced.
The modules below are independently installable, so a user who wants only the status bar, or only
the notifications, can have exactly that — but that's their call to make, not your opening move.
---
## Known gotchas
**Load-bearing — don't simplify these away.** Each cost real debugging time.
| # | Symptom | Cause | Fix | Module |
| --- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 1 | `●` never lights up | "Working" is detected by grepping the pane's footer for `esc to interrupt`, a Claude TUI string, not a public API | Update `WORKING_MARK` at the top of `claude-tmux-status.sh` **and** `claude-switcher.sh` | 3, 8 |
| 2 | `✋`/`✅` never appear for a session | Hook config only applies to **newly started** Claude sessions | Restart the session. Discovery still lists old ones as `👁` — that's intended | 1 |
| 3 | Scripts fail with `declare -A` / substitution errors | macOS ships **bash 3.2** | Scripts avoid associative arrays and modern syntax on purpose; keep that if you edit them | all |
| 4 | Notifier call hangs the hook | `terminal-notifier`'s `-sender` / `-activate` flags can hang | Use only `-title/-message/-group` (and `-remove`) as shown | 6, 7 |
| 5 | Everything looks correctly configured but **no notification ever pops** | macOS suppresses **all** notifications — banners _and_ alerts — while the display is **mirrored or shared**, silently routing them to Notification Center. Costs hours if you record screencasts | System Settings → Notifications → **"Allow notifications when mirroring or sharing the display" = ON**. Diagnose with `system_profiler SPDisplaysDataType \| grep -i mirror` | 6, 7 |
| 6 | Editing Homebrew `terminal-notifier.app`'s `Info.plist` to `alert` changes nothing | macOS seeds an app's alert style from `NSUserNotificationAlertStyle` **only on that bundle id's first registration**. An already-registered app ignores it forever | Use a **copy with its own unused `CFBundleIdentifier`** (Module 7). This is the whole reason that module exists — not cosmetics | 7 |
| 7 | `-remove` silently does nothing | `NSUserNotificationCenter` only manages **its own app's** delivered notifications | The retract must run through the **same bundle that posted** — `ClaudeNotify.app`'s binary, not the Homebrew `terminal-notifier` on `PATH` | 7 |
| 8 | Notifier process spawns constantly / hooks feel sluggish | `running` fires on **every tool call**; an ungated retract launches a GUI binary each time | Gate every retract on `.notify-<id>` existing — it doubles as "an alert is currently posted" | 7 |
| 9 | Alerts pile up unread even after you've seen them | Manual-dismiss is the point, but nothing was retracting them | The retract hooks in Module 7 are not optional polish; without them persistence becomes a chore | 7 |
| 10 | Alert style silently reverts to Banners | Changing `BUNDLE_ID` later makes macOS treat it as a **brand-new app**, re-seeded and re-listed, with the old entry lingering in System Settings | Pick the id once and keep it. Re-running the installer with the same id is safe and preserves the style | 7 |
| 11 | Duplicated tmux hooks after every config reload | `set-hook -ga` **appends** | Use `set-hook -g` (plain) as shown | 5 |
| 12 | A Claude instance never appears | Discovery maps process TTY → tmux pane, so instances **outside tmux** are invisible, as are ones on another host or tmux server | Expected limitation; run Claude inside tmux | 2 |
| 13 | `prefix + a` does nothing / hits a plugin | Key already bound (e.g. `t-smart-tmux-session-manager` binds `T`) | Check `tmux list-keys -T prefix \| grep " a "` and pick a free key | 8 |
| 14 | Editing the `.app` "breaks its signature" | Homebrew's build is **ad-hoc, linker-signed, `Info.plist=not bound`** — editing `Info.plist` is safe and needs no re-sign | Confirm with `codesign -dv <app>`. If yours shows a real TeamIdentifier / sealed resources, re-sign after editing: `codesign --force --sign - <app>` | 7 |
| 15 | Status bar truncates | tmux `status-right-length` defaults to 40 | Set it to ~120 | 4 |
Two smaller ones: state markers are **dotfiles on purpose** (`.viewed-`/`.notify-`) so the
`"$dir"/*` glob that walks state files skips them; and this is **`~/.claude`-global**, monitoring
all your Claude sessions rather than one project.
---
## Dependencies at a glance
| Module | Hard dependencies | Alternatives / notes |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 1 — State tracking | Claude Code CLI, `jq`, bash | None; this is the foundation |
| 2 — Process discovery | `ps`, `awk`, `sort`, `grep`, tmux | `ps -Ao tty,command` works on macOS + Linux; adjust flags for an unusual `ps` (e.g. `-o tty,cmd`) |
| 3 — Renderer | Modules 1–2, tmux, `awk`, `grep` | — |
| 4 — tmux wiring | tmux (any modern version) | — |
| 5 — Viewed collapse | tmux with `focus-events on`, `set-hook` (tmux ≥ 3.0) | Skip it and finished instances stay `✅` until the session ends |
| 6 — Notifications | macOS; `terminal-notifier` **or** built-in `osascript`; AppleScript **Automation** permission for the terminal | Linux: swap `notify()` for `notify-send` and `user_is_looking()` for your WM's focus query (or always return false) |
| 7 — Persistent alerts | Module 6, `terminal-notifier` (**not** the `osascript` fallback), `plutil`, `lsregister` | macOS-only. Module 5 too, for view-triggered dismissal — see the module's note |
| 8 — Switcher | tmux ≥ 3.2 (`display-popup`), `fzf` | `tmux display-menu` (no fuzzy search, no preview) |
Author's baseline for reference: macOS 15.6, Ghostty 1.2.3 (quick-terminal/quake mode), tmux 3.6a,
fish as the interactive shell (irrelevant — every script is bash), Homebrew at `/opt/homebrew`.
Substitute freely; the only environment values that must match reality are `TERMINAL_APP` and any
absolute tool paths.
---
## The implementation
Create `~/.claude/hooks/` and `~/.claude/status/` if absent, and `chmod +x` every script.
Paths use `$HOME` throughout — every one of these runs through a shell (tmux `#(...)`,
`run-shell`, `display-popup -E`, Claude Code hook commands), so it expands. If a path fails to
resolve, substitute an absolute home directory and re-test.
### Module 1 — State tracking via Claude Code hooks (core)
On each Claude lifecycle event, write `~/.claude/status/<session-id>` = `state|epoch|pane|cwd`,
where state is `running` / `permission` / `done`; `clear` deletes it. Files: `claude-status.sh`
(below, shared with Modules 6–7) + the hooks block in `~/.claude/settings.json`.
### Module 2 — Process discovery (core)
Prints the tmux `pane_id` of every live `claude` process by matching process TTY to pane TTY.
**This is what makes idle instances appear at all** — a purely event-driven design misses them,
and shows a stuck "working" indicator after an ESC interrupt.
`~/.claude/hooks/claude-live-panes.sh`:
```bash
#!/usr/bin/env bash
# Outputs the tmux pane_id (one per line) of every live Claude Code CLI instance,
# by matching each `claude` process's TTY to a tmux pane's TTY. Authoritative and
# self-correcting: finds idle instances and ones with no state file.
# TTYs of live `claude` CLI processes. `$1 != "??"` drops the tty-less
# chrome-native-host helper; the basename check keeps only the real CLI.
ttys="$(ps -Ao tty,command 2>/dev/null | awk '
$1 != "??" {
n = split($2, p, "/")
if (p[n] == "claude") print $1
}
' | sort -u)"
[ -n "$ttys" ] || exit 0
# Emit the pane whose tty matches each claude tty (pane_tty is /dev/ttysNNN).
tmux list-panes -a -F '#{pane_tty} #{pane_id}' 2>/dev/null | while read -r ptty pid; do
printf '%s\n' "$ttys" | grep -qxF "${ptty#/dev/}" && printf '%s\n' "$pid"
done
```
### Module 3 — Status-line renderer (core)
For each discovered pane: footer says working → `●`; otherwise overlay the newest state file for
that pane. Three signals, each used for what it's best at — **which instances exist** comes from
process discovery, **is it working right now** from the pane's own footer (never stuck, unlike an
event flag after an interrupt), **everything else** from hook state files.
`~/.claude/hooks/claude-tmux-status.sh`:
```bash
#!/usr/bin/env bash
# Prints the one-line Claude status summary for tmux status-right.
# 1. Which instances exist -> claude-live-panes.sh (TTY -> pane).
# 2. Is it working right now -> the pane footer shows "esc to interrupt".
# 3. Other states -> hook state files ~/.claude/status/<sid>.
# Layout: ●N 👁M ✋<perm names> ✅<done names, cap then ✅+K> (counters lead).
# Written for macOS's stock bash 3.2.
dir="$HOME/.claude/status"
panes_helper="$HOME/.claude/hooks/claude-live-panes.sh"
DONE_CAP=4
WORKING_MARK='esc to interrupt' # Claude's footer shows this only while processing
live_panes=" $(tmux list-panes -a -F '#{pane_id}' 2>/dev/null | tr '\n' ' ') "
# Load state files into arrays; prune files whose pane is truly gone.
n=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r st ts pn cw < "$f"
sid="$(basename "$f")"
if [ -n "$pn" ]; then
case "$live_panes" in
*" $pn "*) : ;;
*) rm -f "$f" "$dir/.viewed-$sid" "$dir/.notify-$sid"; continue ;;
esac
fi
A_STATE[$n]="$st"; A_TS[$n]="${ts:-0}"; A_PANE[$n]="$pn"; A_SID[$n]="$sid"
n=$((n + 1))
done
running=0; viewed=0; done_count=0; perm_l=""; done_l=""
pane_working() { # 0 (true) if the pane's footer shows Claude is processing
tmux capture-pane -p -t "$1" 2>/dev/null | awk 'NF{l=$0} END{print l}' | grep -q "$WORKING_MARK"
}
classify_idle() { # state sid label -- for a pane that is NOT actively working
local state="$1" sid="$2" label="$3"
case "$state" in
permission) perm_l="$perm_l #[fg=colour208,bold]✋${label}#[default]" ;;
done)
if [ -n "$sid" ] && [ -f "$dir/.viewed-$sid" ]; then
viewed=$((viewed + 1))
else
done_count=$((done_count + 1))
[ "$done_count" -le "$DONE_CAP" ] && done_l="$done_l #[fg=colour46,bold]✅${label}#[default]"
fi ;;
*) viewed=$((viewed + 1)) ;; # idle / stuck-running / waiting / untracked
esac
}
for pane in $(bash "$panes_helper" 2>/dev/null); do
label="$(tmux display-message -p -t "$pane" '#{session_name}' 2>/dev/null)"
[ -n "$label" ] || label="claude"
if pane_working "$pane"; then
running=$((running + 1)); continue
fi
bi=-1; bts=-1; k=0
while [ "$k" -lt "$n" ]; do
if [ "${A_PANE[$k]}" = "$pane" ] && [ "${A_TS[$k]}" -gt "$bts" ]; then bts="${A_TS[$k]}"; bi="$k"; fi
k=$((k + 1))
done
if [ "$bi" -ge 0 ]; then classify_idle "${A_STATE[$bi]}" "${A_SID[$bi]}" "$label"
else classify_idle "idle" "" "$label"; fi
done
if [ "$done_count" -gt "$DONE_CAP" ]; then
done_l="$done_l #[fg=colour46,bold]✅+$((done_count - DONE_CAP))#[default]"
fi
out=""
[ "$running" -gt 0 ] && out="$out #[fg=colour39]●${running}#[default]"
[ "$viewed" -gt 0 ] && out="$out #[fg=colour244]👁${viewed}#[default]"
out="$out$perm_l$done_l"
if [ -n "$out" ]; then printf '%s' "${out# }"
else printf '#[fg=colour240]· claude idle#[default]'; fi
```
### Module 4 — tmux wiring (core)
See the `~/.tmux.conf` block at the end of this section; Module 4 is the first two lines.
### Module 5 — "Viewed" collapse (optional)
When you **focus** a finished instance's pane, drop a `.viewed-<id>` marker so `✅name` collapses
into the `👁` count — gated on real focus, so an instance finishing while your terminal is
backgrounded stays a visible `✅`. The same hook retracts that instance's alert (Module 7).
Skipping this: also drop the five `set-hook` lines from `~/.tmux.conf`, and Module 7 loses
view-triggered dismissal (it still retracts on `running`/`clear`).
`~/.claude/hooks/claude-mark-viewed.sh`:
```bash
#!/usr/bin/env bash
# Marks finished ('done') Claude sessions as "viewed" once you actually focus
# their pane, so they collapse from the named list into the 👁 counter.
#
# Invoked (backgrounded) by tmux focus/navigation hooks in ~/.tmux.conf:
# after-select-pane, after-select-window, client-session-changed,
# client-attached, client-focus-in.
# Using client-focus-in means "viewed" only counts when the terminal itself
# has OS focus -- a task finishing while the terminal is backgrounded is NOT hidden.
dir="$HOME/.claude/status"
[ -d "$dir" ] || exit 0
# Focused pane(s): the active pane of the active window of each attached session.
focused=" $(tmux list-panes -a \
-f '#{&&:#{pane_active},#{&&:#{window_active},#{session_attached}}}' \
-F '#{pane_id}' 2>/dev/null | tr '\n' ' ') "
changed=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r state ts pane cwd < "$f"
[ -n "$pane" ] || continue
case "$focused" in *" $pane "*) ;; *) continue ;; esac
sid="$(basename "$f")"
[ "$state" = "done" ] && { marker="$dir/.viewed-$sid"; [ -f "$marker" ] || { touch "$marker"; changed=1; }; }
# --- Module 7: looking at the pane means you've seen it, so retract its macOS alert.
# Those are manual-dismiss and would otherwise pile up until clicked. .notify-<sid>
# doubles as "an alert is currently posted", so this fires once and only when there's
# one to pull down. Applies to `permission` too: the ✋ in the bar is the standing
# reminder. Delete this block if you skip Module 7.
if [ -f "$dir/.notify-$sid" ]; then
"$HOME/.claude/hooks/claude-notify-clear.sh" "$sid"
rm -f "$dir/.notify-$sid"
fi
done
# Only force a redraw when something actually changed.
[ "$changed" -eq 1 ] && tmux refresh-client -S 2>/dev/null
exit 0
```
### Module 6 — Desktop notifications (optional, macOS as written)
Notify on `permission`/`done` **only when the terminal isn't frontmost** (so you're never spammed
while watching), de-duplicated per session, silent. Lives inside `claude-status.sh` below.
### Module 7 — Persistent alerts that retract themselves (optional, macOS)
**The problem it solves:** a banner auto-fades after a few seconds. If you're away from the desk
when an agent finishes, you miss it entirely and the whole notification is wasted. macOS's
**Alerts** style stays on screen until dismissed — but alert style is a **per-app OS setting**,
not something a notification payload can request.
**Why a private app bundle:** macOS seeds an app's style from `NSUserNotificationAlertStyle` in
its `Info.plist`, but **only the first time that bundle id registers**. Homebrew's
`terminal-notifier` is long since registered as `banner`, so editing its plist does nothing — and
flipping its style by hand in System Settings would make _every_ script that uses it persistent.
So: a copy of the bundle with its own `CFBundleIdentifier`. It also makes notifications read as
**"Claude Code"** rather than "terminal-notifier".
**Why it auto-retracts:** persistence without retraction just moves the chore. Every alert is
tagged `-group claude-<session-id>`, which is a precise handle to pull that one back down, from
three places: you focused that instance's pane (Module 5), work resumed, or the session ended.
Only the _focused_ instance's alert is retracted — the others keep standing, which is the point.
`~/.claude/hooks/claude-notifier-install.sh` — run once (and again after
`brew upgrade terminal-notifier`):
```bash
#!/usr/bin/env bash
# (Re)builds ~/.claude/bin/ClaudeNotify.app -- a private copy of terminal-notifier.app used
# by claude-status.sh to post macOS notifications that DO NOT auto-dismiss.
#
# Why a copy: macOS alert style is per-app, and an app's *initial* style is seeded from
# NSUserNotificationAlertStyle in its Info.plist the first time it registers. Homebrew's
# terminal-notifier ships "banner" and is already registered, so the only way to get
# persistent Alerts without hijacking every other terminal-notifier caller is a bundle with
# its own CFBundleIdentifier. Bonus: notifications are attributed to "Claude Code".
#
# Run again after `brew upgrade terminal-notifier` to pick up the new binary. The bundle id
# stays the same, so the alert style already chosen in System Settings is preserved.
set -euo pipefail
# Any reverse-DNS id you have NEVER used before -- the unused-ness is what makes the style
# seeding work. Put your own name/domain in it. Don't change it later (see gotcha 10).
BUNDLE_ID="com.example.claude-notify"
BUNDLE_NAME="Claude Code"
DST="$HOME/.claude/bin/ClaudeNotify.app"
src_bin="$(command -v terminal-notifier || true)"
[ -n "$src_bin" ] || { echo "terminal-notifier not found -- brew install terminal-notifier" >&2; exit 1; }
# Locate terminal-notifier.app. Homebrew's bin/terminal-notifier is a two-line wrapper that
# execs the binary inside the bundle, so read the path straight out of it; other install
# layouts put the CLI inside the bundle itself, so fall back to resolving the symlink.
SRC="$(sed -n 's|.*"\(/.*\.app\)/Contents/MacOS/[^"]*".*|\1|p' "$src_bin" 2>/dev/null | head -1)"
if [ ! -d "${SRC:-}" ]; then
real="$(readlink -f "$src_bin" 2>/dev/null || python3 -c 'import os,sys;print(os.path.realpath(sys.argv[1]))' "$src_bin")"
case "$real" in */Contents/MacOS/*) SRC="${real%/Contents/MacOS/*}" ;; esac
fi
[ -d "${SRC:-}" ] || { echo "could not locate terminal-notifier.app (from $src_bin)" >&2; exit 1; }
mkdir -p "$(dirname "$DST")"
rm -rf "$DST"
cp -R "$SRC" "$DST"
plist="$DST/Contents/Info.plist"
plutil -replace CFBundleIdentifier -string "$BUNDLE_ID" "$plist"
plutil -replace CFBundleName -string "$BUNDLE_NAME" "$plist"
plutil -replace NSUserNotificationAlertStyle -string "alert" "$plist"
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f "$DST"
echo "built $DST ($BUNDLE_ID)"
echo "verify: System Settings > Notifications > \"$BUNDLE_NAME\" -> Alert style = Alerts"
"$DST/Contents/MacOS/terminal-notifier" -title "Claude Code" -message "Persistent alert test -- this should stay until dismissed" -group claude-install-test
```
`~/.claude/hooks/claude-notify-clear.sh`:
```bash
#!/usr/bin/env bash
# Pulls down the macOS alert(s) that claude-status.sh posted for the given session id(s).
# Usage: claude-notify-clear.sh <session-id> [session-id...]
#
# The alerts are manual-dismiss by design (see claude-notifier-install.sh), so something has
# to retract them once they're moot. Callers:
# * claude-mark-viewed.sh -- you focused that instance's pane, so you've seen it
# * claude-status.sh -- the session went `running` again, or ended (`clear`)
#
# NSUserNotificationCenter only manages its own app's delivered notifications, so the remove
# MUST go through the same bundle that posted -- hence the ClaudeNotify.app path first, with
# the same fallback order as claude-status.sh's notify().
set -u
bin="$HOME/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier"
[ -x "$bin" ] || bin="$(command -v terminal-notifier 2>/dev/null || true)"
[ -n "$bin" ] || exit 0
for sid in "$@"; do
[ -n "$sid" ] || continue
"$bin" -remove "claude-$sid" >/dev/null 2>&1 || true
done
exit 0
```
**One manual step, once:** after the installer's test notification appears, open
**System Settings → Notifications → "Claude Code"** and confirm **Alert style = Alerts**. The
`Info.plist` seeding normally sets it; the dropdown is the ground truth, and one click fixes it
permanently if it reads Banners.
### Modules 1 + 6 + 7 — `~/.claude/hooks/claude-status.sh`
The shared entry point. Module boundaries are marked; delete a marked block to skip that module.
```bash
#!/usr/bin/env bash
# Records this Claude session's status for the tmux indicator, and fires a
# macOS notification when the session goes idle while the terminal is not the
# frontmost app (closed or tabbed away from).
# Usage: claude-status.sh <running|permission|done|clear>
# Hook JSON (with .session_id and .cwd) is read from stdin.
state="${1:-}"
dir="$HOME/.claude/status"
mkdir -p "$dir"
input="$(cat)"
sid="$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)"
[ -n "$sid" ] || sid="unknown"
file="$dir/$sid"
notif_marker="$dir/.notify-$sid"
viewed_marker="$dir/.viewed-$sid"
cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
# --- Module 7: an alert from the last idle may still be on screen (they're manual-dismiss).
# Work resuming or the session ending makes it moot, so retract it. Gated on the marker
# existing, since `running` fires on every tool call and must not spawn the notifier each
# time. Delete this block if you skip Module 7.
case "$state" in
running|clear)
[ -f "$notif_marker" ] && "$HOME/.claude/hooks/claude-notify-clear.sh" "$sid"
;;
esac
# --- write / clear state for the tmux status bar (Module 1) ---
if [ "$state" = "clear" ]; then
rm -f "$file" "$notif_marker" "$viewed_marker"
else
# state | epoch | tmux pane (empty when not in tmux) | cwd -- written atomically
# so the renderer / mark-viewed hook never see a half-written line.
printf '%s|%s|%s|%s\n' "$state" "$(date +%s)" "${TMUX_PANE:-}" "$cwd" > "$file.tmp" \
&& mv -f "$file.tmp" "$file"
fi
# New work resumes: reset the notify marker (so the next idle notifies again) and
# drop the viewed marker (a fresh cycle should re-show, not stay collapsed).
[ "$state" = "running" ] && rm -f "$notif_marker" "$viewed_marker"
# ============ Module 6 (+7): notify when idle and you're not looking ============
TERMINAL_APP="ghostty" # System Events process name of YOUR terminal (case-insensitive)
# Module 7's private bundle: same terminal-notifier binary, but its own CFBundleIdentifier
# and NSUserNotificationAlertStyle=alert, so what it posts stays on screen until dismissed.
# Falls back to plain terminal-notifier (banners) if Module 7 isn't installed.
NOTIFIER_BIN="$HOME/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier"
notify() {
local title="$1" msg="$2" bin="$NOTIFIER_BIN"
[ -x "$bin" ] || bin="$(command -v terminal-notifier 2>/dev/null || true)"
if [ -n "$bin" ]; then
# Plain, non-blocking, silent. -sender/-activate can hang; don't add them.
# For it to actually POP (not just land in Notification Center):
# 1. alert style is Banners or Alerts, not None (System Settings > Notifications)
# 2. "Allow notifications when mirroring or sharing the display" = ON
# -- macOS hides ALL notifications while the screen is mirrored/recorded otherwise.
# -group is also the handle claude-notify-clear.sh uses to pull the alert back down.
"$bin" -title "$title" -message "$msg" -group "claude-$sid" >/dev/null 2>&1 || true
else
local t="${title//\\/\\\\}"; t="${t//\"/\\\"}"
local m="${msg//\\/\\\\}"; m="${m//\"/\\\"}"
osascript -e "display notification \"$m\" with title \"$t\"" 2>/dev/null || true
fi
}
# Returns 0 when you ARE looking at the terminal (it's frontmost) -> suppress notify.
user_is_looking() {
local front
front="$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null)"
if [ -n "$front" ]; then
[ "$(printf '%s' "$front" | tr '[:upper:]' '[:lower:]')" = "$(printf '%s' "$TERMINAL_APP" | tr '[:upper:]' '[:lower:]')" ]
return
fi
# Frontmost unknown (e.g. Automation permission denied) -> fall back to tmux clients.
if [ -n "$TMUX" ]; then
local clients; clients="$(tmux list-clients 2>/dev/null | wc -l | tr -d ' ')"
[ "${clients:-0}" -gt 0 ]; return
fi
return 1
}
case "$state" in
done|permission)
# Notify only when you're NOT looking at the terminal, and dedupe on state change.
last="$(cat "$notif_marker" 2>/dev/null || true)"
if ! user_is_looking && [ "$state" != "$last" ]; then
proj="$(basename "$cwd" 2>/dev/null)"
[ -n "$proj" ] && [ "$proj" != "." ] || proj="claude"
if [ "$state" = "permission" ]; then
notify "Claude · needs approval" "✋ $proj needs your approval"
else
notify "Claude · done" "✅ $proj finished — your turn"
fi
printf '%s' "$state" > "$notif_marker"
fi
;;
esac
# ====================== end Modules 6/7 ======================
# Redraw the tmux status bar immediately (server-wide, best-effort).
tmux refresh-client -S 2>/dev/null || true
exit 0
```
### Module 8 — Jump-to switcher popup (optional)
`prefix + a` → fzf popup of every instance (state emoji, `session:window.pane`, project, age)
with a live preview of that pane; `Enter` jumps to it.
`~/.claude/hooks/claude-switcher.sh`:
```bash
#!/usr/bin/env bash
# fzf popup listing every live Claude instance; Enter jumps to its pane.
# Bound to `prefix + a` via display-popup.
dir="$HOME/.claude/status"
panes_helper="$HOME/.claude/hooks/claude-live-panes.sh"
WORKING_MARK='esc to interrupt'
FZF=fzf
command -v fzf >/dev/null 2>&1 || FZF=/opt/homebrew/bin/fzf # fallback path; adjust if needed
now="$(date +%s)"
n=0
shopt -s nullglob
for f in "$dir"/*; do
IFS='|' read -r st ts pn cw < "$f"
A_STATE[$n]="$st"; A_TS[$n]="${ts:-0}"; A_PANE[$n]="$pn"; A_CWD[$n]="$cw"; A_SID[$n]="$(basename "$f")"
n=$((n + 1))
done
pane_working() { tmux capture-pane -p -t "$1" 2>/dev/null | awk 'NF{l=$0} END{print l}' | grep -q "$WORKING_MARK"; }
rows=""
for pane in $(bash "$panes_helper" 2>/dev/null); do
bi=-1; bts=-1; k=0
while [ "$k" -lt "$n" ]; do
if [ "${A_PANE[$k]}" = "$pane" ] && [ "${A_TS[$k]}" -gt "$bts" ]; then bts="${A_TS[$k]}"; bi="$k"; fi
k=$((k + 1))
done
if [ "$bi" -ge 0 ]; then st="${A_STATE[$bi]}"; ts="${A_TS[$bi]}"; cwd="${A_CWD[$bi]}"; sid="${A_SID[$bi]}"
else st="idle"; ts=0; cwd=""; sid=""; fi
if pane_working "$pane"; then
emoji="●"; status="working"
else
case "$st" in
permission) emoji="✋"; status="needs approval" ;;
done) if [ -n "$sid" ] && [ -f "$dir/.viewed-$sid" ]; then emoji="👁"; status="idle"; else emoji="✅"; status="done"; fi ;;
*) emoji="👁"; status="idle" ;;
esac
fi
loc="$(tmux display-message -p -t "$pane" '#{session_name}:#{window_index}.#{pane_index}' 2>/dev/null)"
[ -n "$loc" ] || loc="$pane"
if [ -n "$cwd" ]; then proj="$(basename "$cwd")"
else proj="$(basename "$(tmux display-message -p -t "$pane" '#{pane_current_path}' 2>/dev/null)")"; fi
[ -n "$proj" ] && [ "$proj" != "." ] || proj="—"
if [ "$status" != "working" ] && [ "$ts" -gt 0 ]; then
age=$(( now - ts ))
if [ "$age" -lt 60 ]; then when="${age}s ago"
elif [ "$age" -lt 3600 ]; then when="$((age / 60))m ago"
else when="$((age / 3600))h ago"; fi
else when="$status"; fi
rows="$rows${pane}"$'\t'"$emoji $loc $proj $when"$'\n'
done
if [ -z "$rows" ]; then printf 'No Claude instances.\n'; sleep 1; exit 0; fi
sel="$(printf '%s' "$rows" | "$FZF" \
--ansi --delimiter='\t' --with-nth=2.. --prompt='claude ▸ ' \
--preview 'tmux capture-pane -pe -J -t {1}' --preview-window=right:60%)"
[ -n "$sel" ] || exit 0
pane="$(printf '%s' "$sel" | cut -f1)"
[ -n "$pane" ] || exit 0
sess="$(tmux display-message -p -t "$pane" '#{session_name}' 2>/dev/null)"
tmux switch-client -t "$sess" \; select-window -t "$pane" \; select-pane -t "$pane"
```
### `~/.claude/settings.json` — hooks block (merge into any existing file)
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh running"
}
]
}
],
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh permission"
}
]
},
{
"matcher": "idle_prompt",
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh done"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh done"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.claude/hooks/claude-status.sh clear"
}
]
}
]
}
}
```
- **`PostToolUse → running` matters:** `PreToolUse` fires _before_ a permission prompt, so
`PostToolUse` is what clears the `permission` state after you approve.
- **The `Notification` matcher split** is the reliable way to distinguish a permission prompt from
an idle "your turn" — do **not** regex the notification message text. `matcher` goes on the
group object, exactly as shown.
### `~/.tmux.conf` — additions
```tmux
# --- Claude status indicator (Module 4) ---
set -g status-right "#($HOME/.claude/hooks/claude-tmux-status.sh)"
set -g status-right-length 120 # default 40 truncates once several sessions are open
# Module 5: collapse a finished instance into 👁 once you focus its pane (and retract its
# alert, Module 7). focus-events must be on for client-focus-in to fire.
set -g focus-events on
set-hook -g after-select-pane 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g after-select-window 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-session-changed 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-attached 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
set-hook -g client-focus-in 'run-shell -b "$HOME/.claude/hooks/claude-mark-viewed.sh"'
# Module 8: popup switcher (pick a key that's free for you; verify prefix+a is unbound).
bind-key a display-popup -E -w 80% -h 60% "$HOME/.claude/hooks/claude-switcher.sh"
```
Reload with `tmux source-file ~/.tmux.conf`. Use plain `set-hook -g` (not `-ga`) so reloading
doesn't stack duplicate hooks; these hook names are unset by default and unused by common plugins.
---
## Install order
**Install all of it unless the user said otherwise.** Foundation first, so there's something
visible to demo at every step.
1. `mkdir -p ~/.claude/hooks ~/.claude/status` — and `chmod +x ~/.claude/hooks/*.sh` as you go.
2. **Modules 1–4 (core).** `claude-status.sh` (you can paste the full version now; Modules 6/7's
blocks are inert until their scripts exist), `claude-live-panes.sh`,
`claude-tmux-status.sh`, the settings.json hooks, the first two `~/.tmux.conf` lines.
Reload tmux, **start a fresh Claude session** (gotcha 2) — the bar should light up. _Demoable._
3. **Module 5** — `claude-mark-viewed.sh` + the five `set-hook` lines. _Demoable: `✅` → `👁`._
4. **Module 6** — set `TERMINAL_APP`; grant the terminal **Automation** permission for System
Events on first prompt; on macOS enable _Allow notifications when mirroring or sharing the
display_ (gotcha 5). _Demoable: tab away, wait for a task to finish._
5. **Module 7** — `brew install terminal-notifier`, add `claude-notify-clear.sh`, set `BUNDLE_ID`
in `claude-notifier-install.sh`, run it, then confirm the alert style in System Settings.
_Demoable: an alert that outlives a banner and vanishes when you look at its pane._
6. **Module 8** — `claude-switcher.sh` + the `bind-key`; confirm the key is free first.
---
## Verification quick-checks
| Run this | Expect |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `bash ~/.claude/hooks/claude-live-panes.sh` | one pane id per live Claude instance. Cross-check: `tmux list-panes -a -F '#{pane_id} #{session_name}'` |
| `~/.claude/hooks/claude-tmux-status.sh \| sed -E 's/#\[[^]]*\]//g'` | the rendered line, colours stripped, e.g. `●1 👁2` |
| Start a task in a Claude pane | `●` appears for it; on finish it becomes `✅<session>` |
| Trigger a tool needing approval (in a **fresh** session) | `✋<session>`; approve → `●` → `✅` |
| Focus a `✅` instance's pane | it folds into the `👁` count |
| `prefix + a` | popup lists every instance with a live preview; `Enter` jumps there |
| Tab away from the terminal, let a task finish | one notification, titled **Claude Code** |
| `~/.claude/bin/ClaudeNotify.app/Contents/MacOS/terminal-notifier -list ALL` | a row per still-posted alert, with group `claude-<session-id>` |
| Leave an alert for 30s without touching it | still on screen — that's Alerts style working (a banner would be long gone) |
| Now focus that instance's pane | alert disappears on its own; `-list ALL` no longer shows it |
| `defaults read ~/.claude/bin/ClaudeNotify.app/Contents/Info.plist NSUserNotificationAlertStyle` | `alert` |
**How the known failure modes present:**
- **No notification at all, everything else fine** → mirroring (gotcha 5) first, then Focus mode,
then alert style set to _None_ in System Settings.
- **Notification appears but fades in ~5s** → the bundle's style is Banners, not Alerts: check the
System Settings dropdown for "Claude Code" (gotcha 6). Confirm you're posting through
`ClaudeNotify.app`, not the Homebrew `terminal-notifier` on `PATH`.
- **Alerts appear but never retract** → `-remove` going through the wrong bundle (gotcha 7), or a
stale/missing `.notify-<id>` marker (`ls -a ~/.claude/status/`).
- **`●` never appears, other states fine** → the footer string changed (gotcha 1).
- **`✋`/`✅` never appear for one session** → it predates the hook config (gotcha 2).
---
## Optional extensions
- **Emojis/colours:** the glyphs and `#[fg=colourNNN]` codes in `claude-tmux-status.sh` /
`claude-switcher.sh` (tmux 256-colour palette). `DONE_CAP` controls how many `✅` names show
before collapsing to `✅+K`.
- **Name idle instances too:** move that case out of the `*)` count in `classify_idle`.
- **Click-to-jump alerts:** `terminal-notifier -execute '<command>'` runs a shell command when the
alert is clicked, so a click could switch tmux to the pane that raised it. Worth knowing if you
use a quake/dropdown terminal: `open -a <Terminal>` only activates the app and can't summon a
dropdown window — Ghostty 1.2.3 exposes a `QuickTerminalIntent` App Intent ("Open the Quick
Terminal… if already open, do nothing") reachable from a one-action Shortcut via
`shortcuts run "<name>"`; there is no CLI equivalent (`ghostty +new-window` is GTK/D-Bus,
Linux-only). Deliberately **not** installed here — auto-retract on view proved cleaner than
making the alert something you must click.
- **No tmux?** Modules 1, 6 and 7 work standalone; build a different front-end (menu-bar app,
notification-only setup) on top of the `~/.claude/status/` files.