tmux notifications when an agent is blocked or done: toasts on attached clients, macOS and terminal banners, sound, a JSONL event stream and wait commands.

tmux-ide tells you when an agent becomes blocked or done. Every agent-status change reaches you three ways: notifications for you, an event stream for scripts, and wait commands for coordination.

Notifications and the event stream come from the background updater described in tmux chrome. It runs once any session is adopted or created from the app. Inside the app itself, Home's Needs attention filter and Attention (F7) show the same signal. For exact Claude Code states, run tmux-ide integration install claude once; see Agent detection.

Get notified when an agent is blocked or done

When an agent anywhere in the fleet goes blocked or done, tmux-ide fires a toast. The toast is a tmux message, so it appears on every tmux client attached to the session, including one on another device.

Notifications are configured in ~/.tmux-ide/config.json:

{
  "notifications": {
    "toast": true,
    "macos": false,
    "terminal": true,
    "delaySeconds": 2,
    "sound": "blocked"
  }
}

Channel	Default	What it does
`toast`	`true`	A tmux toast on attached clients
`macos`	`false`	A native macOS notification
`terminal`	`true`	A terminal banner (OSC 9, or OSC 99 for kitty) — works over SSH in terminals that support it
`sound`	`"blocked"`	A sound plus terminal bell on `blocked`, on `all` notifications, or `none`
`delaySeconds`	`2`	OS-level channels wait this long and skip if the agent already moved on; the toast never waits

The macOS helper is bundled with tmux-ide—there is nothing else to install. Its banners use the tmux-ide app icon, follow the system's light/dark icon appearance, and jump to the session that needs you when clicked. On first use, macOS may show its permission card instead of the agent banner. Choose Options → Allow; subsequent agent notifications then appear normally.

See Configuration for the full file.

Ambient status

In the app, pane headers, the sidebar and Home show each agent's state. In tmux chrome sessions, each pane's border chip reflects its agent, e.g. claude · working.

Stream status changes as JSONL

Every status transition is also an append-only JSONL event. Follow it live or snapshot it:

tmux-ide events --follow        # stream transitions as they happen
tmux-ide events --json          # print recent events as JSON

events reads what the background updater writes, so it needs an adopted session or one created from the app. Pipe the stream anywhere — a log, a webhook relay, a status bar of your own. With tmux-ide serve running, events --socket receives pushed events from its local control socket instead.

Wait for an agent in scripts

Two wait commands block until a condition is met, so you can script the fleet. Both exit 0 on match and 1 on timeout.

Wait for a status

tmux-ide wait agent-status work --status blocked --timeout 300000

Blocks until the work session reaches the given agent status (blocked | working | done | idle | unknown). Handy for "notify me when this run needs input" or gating a script on an agent finishing.

Wait for output

tmux-ide wait output %2 --match "Listening on" --timeout 60000
tmux-ide wait output web --match "\berror\b"

Blocks until a pane's (or session's) visible output matches a regex — a portable way to wait on a dev server booting, a build finishing, or an error appearing.

Notifications and events