tmux-agent-sidebar

One tmux sidebar that tracks every Claude Code, Codex, and OpenCode pane across every session and window. See status, background shells, prompts, Git state, activity, and worktrees without switching windows.

Documentation · Getting Started · Features

Features

• Every pane, one view — tracks Claude Code, Codex, and OpenCode panes across all tmux sessions and windows
• Live metadata — prompts, tool calls, response previews, background shell state, wait reasons, task progress, and subagent trees refresh as the agents work
• Worktrees, included — spawn a fresh worktree + agent from the sidebar and tear it down — window, worktree, and branch — in one keystroke
• Desktop notifications — native alerts when an agent finishes, needs permission, or errors out

OpenCode uses a small local plugin bridge instead of per-event hook config. The plugin lives at .opencode/plugins/tmux-agent-sidebar.js and can be symlinked as a single file into ~/.config/opencode/plugins/ so it coexists with any existing plugins.

Requirements

• tmux 3.0+
• TPM (or the manual install in Installation)
• GitHub CLI (optional — required only for PR numbers in the Git tab)

Quick Start

1. Install the plugin

Using TPM:

set -g @plugin 'hiroppy/tmux-agent-sidebar'

Reload tmux (tmux source ~/.tmux.conf), then press prefix + I. The install wizard downloads a pre-built binary or builds from source.

2. Wire up the agent hooks

• Claude Code — register the plugin inside Claude Code:

  /plugin marketplace add ~/.tmux/plugins/tmux-agent-sidebar
  /plugin install tmux-agent-sidebar@hiroppy

• Codex — open a Codex pane, press prefix + e, click the yellow ⓘ badge, copy the setup snippet, paste it into the Codex pane.

• OpenCode — symlink just the plugin file so your existing ~/.config/opencode/plugins/ contents stay untouched:

  mkdir -p ~/.config/opencode/plugins
  ln -sf ~/.tmux/plugins/tmux-agent-sidebar/.opencode/plugins/tmux-agent-sidebar.js \
    ~/.config/opencode/plugins/tmux-agent-sidebar.js

Full walkthroughs: Claude Code setup · Codex setup · OpenCode setup

3. Toggle the sidebar

prefix + e toggles the sidebar in the current window, prefix + E toggles it everywhere.

Documentation

The documentation site covers every feature and option:

• Agent pane breakdown
• Worktree lifecycle
• Activity log · Git tab · Notifications
• Agent support matrix
• Keybindings · tmux options · Scripting

Development

Symlink the plugin directory to your working copy so builds are picked up without copying:

rm -rf ~/.tmux/plugins/tmux-agent-sidebar
ln -s <path-to-this-repo> ~/.tmux/plugins/tmux-agent-sidebar
cargo build --release

Toggle the sidebar off → on to pick up the new binary.

Picking up local builds for the Claude Code plugin

If you also installed this as a Claude Code plugin (/plugin), its install path holds a copy of the released binary that hooks resolve before falling back to target/release/. To make local builds flow through Claude Code hooks too, replace that copy with a symlink to your working copy:

# Replace the cached plugin install with a symlink to your repo
PLUGIN_CACHE=~/.claude/plugins/cache/<owner>/tmux-agent-sidebar/<version>
rm -rf "$PLUGIN_CACHE"
ln -s <path-to-this-repo> "$PLUGIN_CACHE"

Also remove the stale release binary at bin/tmux-agent-sidebar in your repo if present — both the tmux launcher and hook.sh prefer bin/ over target/release/, so a leftover binary there will mask cargo build --release output:

rm -f bin/tmux-agent-sidebar

Note: Claude Code's plugin updater may overwrite the symlink on a future update; re-run the symlink step if that happens.

License

MIT