A tmux sidebar that monitors all AI coding agents (Claude Code, Codex) across all sessions and windows — statuses, prompts, Git info, activity logs, and more in one place.
- Cross-session monitoring — Shows all agents from every tmux session and window in one sidebar
- Activity log — Streams each tool invocation (Read, Edit, Bash, etc.) per agent in real time
- Task & subagent tracking — Displays task progress (e.g.
3/7) and spawned subagents as a parent-child tree - Git integration — Shows branch name, ahead/behind counts, PR number (
gh), and per-file diff stats - Worktree-aware grouping — Groups agents by the same repo, including worktrees, so related panes stay together
- Spawn & remove worktrees from the sidebar — Press
n(or click+next to a repo header) to create a newgit worktree, open a tmux window in it, and launch an agent in one step. Remove it later withx, or click the red×next to the branch on any spawn-created row - Pane metadata — Shows listening localhost ports and execution command info for each pane
 |
|
- tmux 3.0+
- TPM (for plugin installation)
- GitHub CLI (optional, for displaying PR numbers in the Git tab)
- Rust (only if building from source)
Option A: Installation with TPM (recommended).
Add the plugin to your tmux.conf:
set -g @plugin 'hiroppy/tmux-agent-sidebar'Reload tmux.conf (tmux source ~/.tmux.conf), then press prefix + I to install. On the first run, an install wizard prompts you to download a pre-built binary or build from source.
To update later, press prefix + U in TPM's plugin list and select tmux-agent-sidebar. The install wizard runs again if the bundled binary has changed.
Option B: Manual
- Clone the repository:
git clone https://github.com/hiroppy/tmux-agent-sidebar.git ~/.tmux/plugins/tmux-agent-sidebar- Add the plugin to your
tmux.conf:
run-shell ~/.tmux/plugins/tmux-agent-sidebar/tmux-agent-sidebar.tmux- Install the binary using one of the following methods:
# macOS (Apple Silicon)
curl -fSL https://github.com/hiroppy/tmux-agent-sidebar/releases/latest/download/tmux-agent-sidebar-darwin-aarch64 \
-o ~/.tmux/plugins/tmux-agent-sidebar/bin/tmux-agent-sidebar
chmod +x ~/.tmux/plugins/tmux-agent-sidebar/bin/tmux-agent-sidebar
cd ~/.tmux/plugins/tmux-agent-sidebar
cargo build --releaseAfter updating tmux.conf, press prefix + r to reload the config.
The sidebar receives status updates through agent hooks. Add the following hook definitions to your agent settings.
The repository ships as a Claude Code plugin, so the hooks register themselves.
Inside Claude Code, register the marketplace and install the plugin:
/plugin marketplace add ~/.tmux/plugins/tmux-agent-sidebar
/plugin install tmux-agent-sidebar@hiroppyEither form wires up the Claude Code hooks. Run /reload-plugins (or restart Claude Code) to activate them.
If your environment can' use plugin, you will be able to register hooks to your settings.json using below prompt.
Run ~/.tmux/plugins/tmux-agent-sidebar/target/release/tmux-agent-sidebar setup claude (fall back to ~/.tmux/plugins/tmux-agent-sidebar/bin/tmux-agent-sidebar if that path is missing). Add these hooks to ~/.claude/settings.json. If hooks already exist, merge them without making destructive changes.
- Open a Codex pane in tmux and focus it.
- Press
prefix + eto toggle the sidebar. A yellowⓘbadge appears in the top row of the sidebar when required hooks are missing. - Click
ⓘ, then click[copy]next tocodexin the Notices popup. - Switch back to the Codex pane and paste. Codex will run
tmux-agent-sidebar setup codexand merge the hooks into~/.codex/hooks.json.
| Key | Action |
|---|---|
prefix + e |
Toggle sidebar (default, customizable) |
prefix + E |
Toggle sidebar in all windows (default, customizable) |
j / Down |
Move selection down (filter → agents → bottom panel) |
k / Up |
Move selection up |
h / Left |
Previous status filter when the filter bar is focused |
l / Right |
Next status filter when the filter bar is focused |
r |
Open repo filter popup (filter bar only) |
n |
Spawn a new worktree + agent for the selected row's repo |
x |
Remove the selected spawn-created pane (opens the close modal) |
Enter |
Jump to the selected agent's pane / confirm the repo popup |
Tab |
Cycle status filter (All → Running → Waiting → Idle → Error) |
Shift+Tab |
Switch bottom panel tab (Activity / Git) |
Esc |
Return focus to the agents panel / close the repo popup |
Mouse click + |
Open the spawn modal for that repo (right edge of each repo header) |
Mouse click × |
Open the close-pane modal for that spawn-created worktree (red × next to the branch) |
| Mouse click | Jump to an agent's pane / filter by status / open the repo popup |
Opened with n or by clicking the + button next to a repo header.
| Key | Action |
|---|---|
| Text keys | Type the name (used as the branch slug and tmux window name, e.g. add login form → agent/add-login-form) |
↑ / ↓ / Tab / Shift+Tab |
Move focus between NAME / AGENT / MODE fields |
← / → |
Cycle the value when the agent or mode field has focus |
Enter |
Create the worktree + window and launch the agent |
Esc / click outside |
Cancel |
Opened with x on a spawn-created pane.
| Key | Action |
|---|---|
y / Enter |
Close the tmux window, remove the git worktree (--force), and delete the branch the spawn created (git branch -D) |
c |
Close the tmux window only, keep the worktree and branch on disk |
n / Esc |
Cancel |
Branches are force-deleted because the sidebar auto-generates them under the agent/ prefix for short-lived explorations; squash/rebase-merged work would otherwise be refused by the non-forced git branch -d check. Recover via git reflog if needed.
| Feature | Claude Code | Codex | Notes |
|---|---|---|---|
| Status tracking (running / idle / error) | ✅ | ✅ | Driven by SessionStart / UserPromptSubmit / Stop |
| Prompt text display | ✅ | ✅ | Saved from UserPromptSubmit |
Response text display (▷ ...) |
✅ | ✅ | Populated from Stop payload |
| Waiting status + wait reason | ✅ | ❌ | Populated from Notification, PermissionDenied, and TeammateIdle (all Claude-only) |
| API failure reason display | ✅ | ❌ | StopFailure is wired only for Claude |
| Permission badge | ✅ (plan / edit / auto / !) |
✅ (auto / ! only) |
Codex badges are inferred from process arguments |
| Git branch display | ✅ | ✅ | Uses the pane cwd; Claude updates dynamically via CwdChanged |
| Elapsed time | ✅ | ✅ | Since the last prompt |
| Task progress | ✅ | ❌ | Requires PostToolUse; Codex fires PostToolUse only for Bash, so task progress from tools is unavailable |
| Task lifecycle notifications | ✅ | ❌ | Requires TaskCreated / TaskCompleted |
| Subagent display | ✅ | ❌ | Requires SubagentStart / SubagentStop |
| Activity log | ✅ | ✅ (Bash only) | Codex's PostToolUse fires only for Bash tool calls; Read/Edit/Write/Grep/Glob/etc. are not reported |
| Worktree lifecycle tracking | ✅ | ❌ | Requires WorktreeCreate / WorktreeRemove |
- Waiting status (Claude Code) — After you approve a permission prompt, the status stays
waitinguntil the next hook event fires. This is a limitation of the Claude Code hook system. - Codex hook coverage — Codex emits
SessionStart,UserPromptSubmit,Stop, andPostToolUse.PostToolUseis limited to theBashtool (Codex's schema typestool_inputas{ command: string }), so the Codex activity log shows only Bash commands. Waiting status, task progress, subagent display, and worktree tracking remain unavailable.
Most options can be set before loading the plugin in your tmux.conf:
# Sidebar
set -g @sidebar_key T # keybinding (default: e)
set -g @sidebar_key_all Y # keybinding for all windows (default: E)
set -g @sidebar_width 32 # width in columns or % (default: 15%)
set -g @sidebar_bottom_height 20 # bottom panel height in lines (default: 20, 0 to hide)
set -g @sidebar_auto_create off # disable auto-create on new windows (default: on)
# Spawn worktree modal defaults (optional)
set -g @agent-sidebar-default-agent codex # agent launched by `n` (default: claude)
set -g @agent-sidebar-branch-prefix wip/ # branch prefix for new worktrees (default: agent/)
# Colors (256-color palette numbers) — all defaults live in src/ui/colors.rs
set -g @sidebar_color_all 111 # selected "all" filter icon (default: 111 sky blue)
set -g @sidebar_color_running 114 # selected running filter icon and running pane status (default: 114 green)
set -g @sidebar_color_waiting 221 # selected waiting filter icon, waiting pane status, version banner (default: 221 yellow)
set -g @sidebar_color_idle 110 # selected idle filter icon and idle pane status (default: 110 soft blue)
set -g @sidebar_color_error 167 # selected error filter icon and error pane status (default: 167 soft red)
set -g @sidebar_color_filter_inactive 245 # unselected status filter icons and zero counts (default: 245 mid gray)
set -g @sidebar_color_border 240 # unfocused panel borders and tab separators (default: 240 dark gray)
set -g @sidebar_color_accent 153 # active pane marker, focused repo header, focused bottom panel border, repo popup border (default: 153 pale sky blue)
set -g @sidebar_color_session 39 # session name (default: 39 blue)
set -g @sidebar_color_agent_claude 174 # Claude brand color (default: 174 terracotta)
set -g @sidebar_color_agent_codex 141 # Codex brand color (default: 141 purple)
set -g @sidebar_color_text_active 255 # primary text (active rows, counts, filtered repo label) (default: 255 white)
set -g @sidebar_color_text_muted 252 # secondary text (tree branches, empty-state messages, inactive bottom tabs, activity log labels) (default: 252 light gray)
set -g @sidebar_color_text_inactive 244 # body text of unfocused pane rows (prompt/response, idle hint) (default: 244 mid gray)
set -g @sidebar_color_port 246 # port numbers (default: 246 light gray)
set -g @sidebar_color_wait_reason 221 # wait reason text (default: 221 yellow)
set -g @sidebar_color_selection 239 # selected row background (default: 239 slightly lighter dark gray)
set -g @sidebar_color_branch 109 # git branch name (default: 109 teal)
set -g @sidebar_color_task_progress 223 # task progress summary (default: 223 pale yellow)
set -g @sidebar_color_subagent 73 # subagent tree (default: 73 green)
set -g @sidebar_color_commit_hash 221 # commit hash (default: 221 yellow)
set -g @sidebar_color_diff_added 114 # added diff lines (default: 114 green)
set -g @sidebar_color_diff_deleted 174 # deleted diff lines (default: 174 terracotta)
set -g @sidebar_color_file_change 221 # file change stats (default: 221 yellow)
set -g @sidebar_color_pr_link 117 # PR link / number (default: 117 blue)
set -g @sidebar_color_section_title 109 # section titles (default: 109 teal)
set -g @sidebar_color_activity_timestamp 109 # activity timestamps (default: 109 teal)
set -g @sidebar_color_response_arrow 81 # response arrow (default: 81 bright cyan)
# Icons (Unicode glyphs; defaults keep the current look)
set -g @sidebar_icon_all ≡ # status filter bar "all" icon
set -g @sidebar_icon_running ● # running status icon
set -g @sidebar_icon_waiting ◐ # waiting status icon
set -g @sidebar_icon_idle ○ # idle status icon
set -g @sidebar_icon_error ✕ # error status icon
set -g @sidebar_icon_unknown · # unknown status icon
run-shell ~/.tmux/plugins/tmux-agent-sidebar/tmux-agent-sidebar.tmuxThe sidebar stores agent status in tmux pane options, which you can read from your own scripts or status bar:
# Get a specific pane's agent status
tmux show -t "$pane_id" -pv @pane_status
# Returns: running / waiting / idle / error / (empty)
# Get agent type
tmux show -t "$pane_id" -pv @pane_agent
# Returns: claude / codex / (empty)This is useful for integrating agent status into your tmux status bar, custom scripts, or notifications.
- Remove the
set -g @plugin(orrun-shell) line from yourtmux.conf - Remove hook entries or plugins from your Claude Code / Codex settings
- Remove the plugin directory:
rm -rf ~/.tmux/plugins/tmux-agent-sidebar
Symlink the plugin directory to your working copy so that builds are picked up without copying artifacts. If TPM already cloned the plugin, remove it first:
rm -rf ~/.tmux/plugins/tmux-agent-sidebar
ln -s <path-to-this-repo> ~/.tmux/plugins/tmux-agent-sidebarThen build — the binary that your local tmux sidebar loads is replaced in place. Toggle the sidebar off → on to pick up the new build.
cargo build --release
# or, enable the `debug` feature to force-display notices (version, missing hooks, claude plugin)
cargo build --release --features debugThis repository is itself a Claude Code marketplace (see .claude-plugin/marketplace.json). Because ~/.tmux/plugins/tmux-agent-sidebar is symlinked to the repo, the same install flow from 3.1 Claude Code already points Claude Code at your working copy:
/plugin marketplace add ~/.tmux/plugins/tmux-agent-sidebar
/plugin install tmux-agent-sidebar@hiroppy
After editing plugin files, pick up changes without reinstalling:
hooks/hooks.json,.claude-plugin/plugin.json,hook.sh— run/reload-pluginsin Claude Code (or restart it).- Rust sources —
cargo build --release, then toggle the sidebar off → on.
To iterate from a git worktree, register the worktree path as its own marketplace:
/plugin marketplace add <worktree-path>
/plugin install tmux-agent-sidebar@hiroppy