sidebar

Toggles a live agent status sidebar on the left side of all tmux windows. Shows all active agents across all sessions and projects with live status updates.

workmux sidebar            # Toggle sidebar on/off

What it shows

Each agent row displays:

• Status icon (working/waiting/done with spinner animation)
• Project and worktree name (e.g. myproject/fix-bug)
• Elapsed time since last status change

Keybindings

Key	Action
j/k	Navigate up/down
Enter	Jump to agent pane
g/G	Jump to first/last
q	Quit sidebar

Navigation commands

Switch between agents from any tmux pane, in the same order shown in the sidebar:

Command	Action
workmux sidebar next	Switch to the next agent (wraps)
workmux sidebar prev	Switch to the previous agent (wraps)
workmux sidebar jump <N>	Jump to the Nth agent (1-indexed)

Example tmux keybindings

# Alt+j / Alt+k to cycle agents (no prefix needed)
bind -n M-j run-shell "workmux sidebar next"
bind -n M-k run-shell "workmux sidebar prev"

# Alt+1..9 to jump directly
bind -n M-1 run-shell "workmux sidebar jump 1"
bind -n M-2 run-shell "workmux sidebar jump 2"
bind -n M-3 run-shell "workmux sidebar jump 3"
# ...

# Or with prefix key (avoids terminal conflicts)
bind C-j run-shell "workmux sidebar next"
bind C-k run-shell "workmux sidebar prev"

Configuration

sidebar:
  width: 40 # absolute columns (default: "10%", clamped 25-50)
  # width: "15%"  # or percentage of terminal width
  layout: tiles # "compact" or "tiles" (default)

Explicit width values bypass the default 25-50 column clamp (minimum 10 columns). Layout preference can also be toggled at runtime with v and is persisted across restarts.

How it works

When enabled, a background daemon polls tmux state every 2 seconds and pushes snapshots to each sidebar pane over a Unix socket. The sidebar creates a narrow tmux pane on the left side of every existing window using a full-height split. A tmux hook (after-new-window) ensures newly created windows also get a sidebar automatically.

Running workmux sidebar again disables the sidebar globally, killing all sidebar panes, the daemon, and removing hooks.

Limitations

• tmux only (other backends are not supported yet)

Example tmux binding

bind C-t run-shell "workmux sidebar"