tmux-claude-status-tabs

tmux-claude-status-tabs

Run five Claude sessions in five windows and you spend your day guessing which tab wants you. This makes the bar answer it at a glance.

The states

running — the spinner ticks while Claude works

input — Claude asked you something and waits, amber ?

permission — blocked on an approval, red !

done — finished without a question, green ✓

The workflow

Event-driven, continuously verified. Claude Code hooks repaint the tab within half a second of each lifecycle event, and a verifier checks every tab against Claude Code's own per-session status a few seconds apart — so even the transitions Claude never reports (Esc, a granted permission, a stop hook resuming the turn, subagents working under a finished turn) can't leave a tab lying. Questions latch, finished turns hold their colour. The whole state machine is pinned by 300+ assertions run in CI, including contract tests against real Claude payloads and session files.

Curious why the tab never lies? Read how it works.

Install

The installer copies the hook scripts to ~/.claude/hooks/ and merges their wiring into ~/.claude/settings.json (backs up first, preserves existing hooks).

Requires tmux ≥ 3.0, jq, and the Claude Code CLI.

Then add one of these to ~/.tmux.conf and reload:

- Drop-in: source-file /path/to/tmux-claude-status-tabs/tmux/claude-state.conf
- Your own theme: prepend the #{?...} fragment from tmux/claude-state-prefix.txt to your existing window-status-format and window-status-current-format.

Desktop notifications (macOS)

Built in via osascript — nothing extra to install. With alerter (brew install vjeantet/tap/alerter) notifications become clickable: one click focuses your terminal and jumps to the window where Claude is waiting. Other platforms skip notifications…