Displaying AI Coding Agent State in Tmux Window Lists
Managing multiple CLI agent sessions like Claude Code and Codex in tmux often obscures which pane is busy, blocked, or finished. By walking the process tree and parsing screen output rather than terminal titles, developers can render dynamic status indicators directly in the tmux window list.
Impact: Medium
Why it matters
You can monitor long-running background coding agents across multiple windows without constantly switching contexts or switching to third-party multiplexers.
TL;DR
- 01Claude Code and Codex do not update tmux window titles dynamically; screen inspection via capture-pane is mandatory.
- 02Process detection must walk descendant PIDs via pgrep because CLI installers run from versioned directories.
- 03Rule ordering matters: Claude requires working state checks first, while Codex requires approval prompt checks first.
Key facts
- Multiplexing target
- Native tmux status line without replacing multiplexer
- Supported agents
- Claude Code, Codex, Grok, pingme
- Detection technique
- Process-tree traversal + tmux capture-pane terminal scraping
The Fragility of Title and Command Hooks
When multiplexing agent CLI sessions such as Claude Code, Codex, and Grok, developers instinctively look at pane_title or pane_current_command. However, Claude Code sets pane_title once with the session name and never modifies it, ignoring standard OSC status escape updates. Grok emits dynamic braille spinners (⠋, ⠸) in the title, but relying on titles makes cross-agent behavior inconsistent. Furthermore, checking pane_current_command fails because launchers execute versioned binaries (such as 2.1.267 or grok-1.0.30-mac), stripping the recognisable program identity.
Combining Process Trees with Screen Buffer Scraping
The robust pattern pairs process identification with direct terminal buffer inspection:
1. Identify the agent binary: Traverse descendant process IDs via pgrep -P and match the executable name (claude, codex, grok, pingme). 2. Capture visible screen state: Use tmux capture-pane on the bottom lines of the target pane. 3. Apply agent-specific state rules:
- Claude: Treat
esc to interruptasworking, a bare prompt (❯) asidle, and permission queries (do you want to proceed?,waiting for permission) asaction. - Codex: Prioritize approval prompts (
press enter to confirm or esc to cancel) before checkingesc to interruptto prevent busy states from masking user blocking. - Grok: Match interactive footer cues (
<n>/<n>:select,Allow …?) for approvals and[stop]|Ctrl+c:cancelfor execution.
By feeding these evaluation results into your window-status-format, tmux flags stalled or working tasks directly in tab headers without external UI overhead.
Try it in 2 minutes
agent_in_pane() {
local root="$1" pids="$root" queue="$root"
while [ -n "$queue" ]; do
local pid="${queue%% *}"
queue="${queue#$pid}"; queue="${queue# }"
for c in $(pgrep -P "$pid" 2>/dev/null); do
pids="$pids $c"; queue="$queue $c"
done
done
ps -o comm= -p $pids 2>/dev/null | sed -nE 's|.*/||; /^(claude|codex|grok)$/p' | head -n 1
}bash
✓ When to use
- When managing 3 or more concurrent autonomous CLI agents across tmux tabs.
- When coding agents block on shell permission checks out of view.
✕ When NOT to use
- When running agent workloads exclusively within GUI IDEs such as Cursor or Windsurf.
- When you prefer standalone terminal multiplexers designed specifically for agent orchestration.
What to do today
- Add a pgrep process tree walker script to your dotfiles to identify active agent binaries per pane.
- Configure tmux capture-pane pattern matching for 'esc to interrupt' and confirmation prompts.
- Inject custom status icons into the tmux window-status-current-format configuration.
Sources