tcmux

tcmux is a terminal and coding agent mux viewer.

Supports Claude Code, GitHub Copilot CLI, and Codex CLI.

Usage

$ tcmux list-windows  # List coding agent instances in tmux windows (alias: lsw)
0: editor (1 panes) ✻ Fix login bug [Idle]
2: server (2 panes) ✻ Add API endpoint [Running (1m 30s)], ✻ Write tests [Idle]
5: docs (1 panes) ✻ Update README [Idle]
7: review (1 panes) ⬢ Review PR [Waiting]
8: codex (1 panes) ❂ Refactor parser [Running]

$ tcmux list-windows -A  # Show all windows, not just coding agents
0: editor (1 panes) ✻ Fix login bug [Idle]
1: shell (1 panes)
2: server (2 panes) ✻ Add API endpoint [Running (1m 30s)], ✻ Write tests [Idle]
3: logs (1 panes)
4: htop (1 panes)
5: docs (1 panes) ✻ Update README [Idle]
7: review (1 panes) ⬢ Review PR [Waiting]
8: codex (1 panes) ❂ Refactor parser [Running]

$ tcmux list-sessions  # List tmux sessions with coding agent status (alias: ls)
dev: 7 windows (attached) - 3 Idle, 1 Running, 1 Waiting
main: 2 windows - 1 Idle
work: 1 window

$ tcmux stats  # Show total coding agent stats across all sessions
I:4 R:1 W:1

$ tcmux stats -F "#{agent_status}"
4 Idle, 1 Running, 1 Waiting

Supported Agents

Agent	Icon	Detection
Claude Code	✻	pane title starts with `✳` or Braille spinner, process is `claude` or `node`
GitHub Copilot CLI	⬢	process is `copilot`
Codex CLI	❂	process name starts with `codex` (e.g. `codex`, `codex-aarch64-a`)

Options

list-windows:

Option	Description
`-A, --all-windows`	Show all windows, not just coding agents. Use this when replacing `tmux list-windows` with tcmux
`-a, --all-sessions`	List windows from all sessions
`-t, --target-session`	Specify target session
`-F, --format`	Specify output format (tmux-compatible with tcmux extensions)

stats:

Option	Description
`-F, --format`	Specify output format (default: `I:#{total_idle} R:#{total_running} W:#{total_waiting}`)

Global:

Option	Description
`--color`	When to use colors: `always`, `never`, or `auto` (default: `auto`)

Format Variables

tcmux supports all tmux format variables (e.g., #{window_index}, #{window_name}) plus:

Variable	Description
`#{agent_status}`	Coding agent status (context-dependent)
`#{total_idle}`	Total idle count (stats only)
`#{total_running}`	Total running count (stats only)
`#{total_waiting}`	Total waiting count (stats only)
`#{total_agents}`	Total agent count (stats only)

list-windows: ✻ Fix login bug [Idle], ⬢ Review PR [Running], ❂ Refactor parser [Running (plan mode)]
list-sessions: 2 Idle, 1 Running
stats: 4 Idle, 1 Running, 1 Waiting

Example:

$ tcmux list-windows -F "#{window_index}:#{window_name} #{agent_status}"
$ tcmux list-sessions -F "#{session_name}: #{agent_status}"
$ tcmux stats -F "💤#{total_idle} 🏃#{total_running} ⏳#{total_waiting}"

Recipe: Window switcher with coding agent status

Replace tmux list-windows with tcmux list-windows -A in your .tmux.conf:

# before
bind-key w run-shell "tmux list-windows | fzf --tmux | cut -d: -f1 | xargs tmux select-window -t"

# after
bind-key w run-shell "tcmux list-windows -A --color=always | fzf --ansi --tmux | cut -d: -f1 | xargs tmux select-window -t"

# screenshot example
bind -r w run-shell "tcmux lsw -A --color=always | fzf --ansi --layout reverse --tmux 80%,50% --color='pointer:24' | cut -d: -f 1 | xargs tmux select-window -t"

Install

homebrew tap:

$ brew install k1LoW/tap/tcmux

go install:

$ go install github.com/k1LoW/tcmux@latest

manually:

Download binary from releases page