tmux options

Most options must be set before loading the plugin in your tmux.conf. Color values can be xterm 256-color numbers (0-255) or six-digit hex colors (#RRGGBB or RRGGBB); icons can be any Unicode glyph.

Sidebar behavior

Option	Default	Description
@sidebar_key	e	Prefix-triggered keybinding to toggle the sidebar in the current window
@sidebar_key_all	E	Prefix-triggered keybinding to toggle the sidebar in all windows
@sidebar_width	15%	Width in columns or as a percentage
@sidebar_position	left	Sidebar placement (left or right)
@sidebar_bottom_height	20	Bottom panel height in lines (set 0 to hide)
@sidebar_auto_create	on	Auto-create the sidebar on new windows (set off to disable)
@sidebar_auto_create_delay	0	Seconds to defer auto-create after a window opens, so a declaratively-built window (e.g. tmuxinator’s select-layout) finishes before the sidebar pane is injected; accepts fractional seconds. 0 keeps the create synchronous
@sidebar_notifications	on	Master switch for desktop notifications
@sidebar_notifications_events	unset	Restrict events — see Notifications
@sidebar_pet	off	Show the animated pet in a 5-row band above the bottom panel

Worktree spawn defaults

Option	Default	Description
@agent-sidebar-default-agent	claude	Agent launched by n (also accepts codex)
@agent-sidebar-branch-prefix	agent/	Branch prefix for new worktrees
@agent-sidebar-worktree-dir	.worktrees	Repo-relative directory for sidebar-spawned worktrees; absolute paths and .. are rejected

Status and filter colors

Option	Default	What it paints
@sidebar_color_all	111 (sky blue)	Selected “all” filter icon
@sidebar_color_running	114 (green)	Selected running/background filter icon and running/background pane status
@sidebar_color_waiting	221 (yellow)	Selected waiting filter icon, waiting pane status, version banner
@sidebar_color_idle	110 (soft blue)	Selected idle filter icon and idle pane status
@sidebar_color_error	167 (soft red)	Selected error filter icon and error pane status
@sidebar_color_filter_inactive	245 (mid gray)	Unselected status filter icons and zero counts

Structural colors

Option	Default	What it paints
@sidebar_color_border	240 (dark gray)	Unfocused panel borders and tab separators
@sidebar_color_accent	153 (pale sky blue)	Active pane marker, focused repo header, focused bottom panel border, repo popup border — the brand color
@sidebar_color_session	39 (blue)	Session name
@sidebar_color_selection	239 (dark gray)	Selected row background

Agent colors

Option	Default	What it paints
@sidebar_color_agent_claude	174 (terracotta)	Claude brand color
@sidebar_color_agent_codex	141 (purple)	Codex brand color
@sidebar_color_agent_opencode	117 (light blue)	OpenCode brand color

Text colors

Option	Default	What it paints
@sidebar_color_text_active	255 (white)	Primary text — active rows, counts, filtered repo label
@sidebar_color_text_muted	252 (light gray)	Secondary text — tree branches, empty-state messages, inactive bottom tabs, activity log labels
@sidebar_color_text_inactive	244 (mid gray)	Body text of unfocused pane rows — prompt / response, idle hint
@sidebar_color_port	246 (light gray)	Port numbers
@sidebar_color_wait_reason	221 (yellow)	Wait reason text
@sidebar_color_response_arrow	81 (bright cyan)	Response arrow

Task and sub-agent colors

Option	Default	What it paints
@sidebar_color_task_progress	223 (pale yellow)	Task progress summary
@sidebar_color_subagent	73 (soft teal)	Sub-agent tree

Git tab colors

Option	Default	What it paints
@sidebar_color_branch	109 (teal)	Git branch name
@sidebar_color_commit_hash	221 (yellow)	Commit hash
@sidebar_color_diff_added	114 (green)	Added diff lines
@sidebar_color_diff_deleted	174 (terracotta)	Deleted diff lines
@sidebar_color_file_change	221 (yellow)	File change stats
@sidebar_color_pr_link	117 (light blue)	PR link / number

Section titles and timestamps

Option	Default	What it paints
@sidebar_color_section_title	109 (teal)	Section titles
@sidebar_color_activity_timestamp	109 (teal)	Activity timestamps

Status icons

Any Unicode glyph works. Make sure the glyphs render in your terminal font.

Option	Default	Meaning
@sidebar_icon_all	≡	Status filter bar “all” icon
@sidebar_icon_running	●	Running status icon
@sidebar_icon_background	◎	Background shell status icon
@sidebar_icon_waiting	◐	Waiting status icon
@sidebar_icon_idle	○	Idle status icon
@sidebar_icon_error	✕	Error status icon
@sidebar_icon_unknown	·	Unknown status icon

Example config

# Behavior
set -g @sidebar_key T
set -g @sidebar_width 32
set -g @sidebar_position right
set -g @sidebar_bottom_height 25
set -g @sidebar_notifications_events "stop,notification"
set -g @agent-sidebar-default-agent codex

# Colors
set -g @sidebar_color_accent 117
set -g @sidebar_color_agent_claude "#d97757"
set -g @sidebar_color_agent_opencode 39

# Icons
set -g @sidebar_icon_running '▶'
set -g @sidebar_icon_error   '⚠'

run-shell ~/.tmux/plugins/tmux-agent-sidebar/tmux-agent-sidebar.tmux