Quick start
# Add to your tmux.conf
set -g @plugin 'sandudorogan/tmux-pane-tree'
# Optional: auto-install agent hooks
set -g @tmux_pane_tree_install_agent_hooks 1
# Reload tmux, then prefix + IA tmux sidebar plugin
Your tmux workspace, always in view.
tmux-pane-tree keeps a persistent, interactive sidebar on the left side of every window. Browse sessions, windows, and panes as a Unicode tree — with live status badges showing what your AI coding agents are doing in real time.
- tmux 3.0+Supported baseline
- Keyboard-firstVim-style navigation
- Agent-awareClaude, Codex, Cursor, OpenCode
Features
What it does
Interactive tree
Browse sessions, windows, and panes as a Unicode tree. Press Enter to jump to any pane.
The sidebar renders your entire tmux hierarchy as a navigable tree with j/k navigation, gg/G jumps, and Enter to switch panes. The tree updates in real time as you create or close panes.
- j / k to move up and down the tree
- gg / G to jump to the top or bottom
- Enter to switch to the selected pane
- q to close the sidebar
Live agent badges
Real-time status badges for Claude, Codex, Cursor, and OpenCode coding agents.
See at a glance which agents are working, waiting, done, or errored. Badges update via lightweight hook scripts and clear automatically when you focus the pane.
⏳ Running
❓ Needs input
✅ Done
❌ Error
Pane app icons
Per-pane icons for shells, coding agents, lazygit, yazi, vim, and more with auto-detection.
Auto-detects Nerd Fonts and switches to rich glyphs automatically. Falls back to ASCII or Unicode when no Nerd Font is installed. Every icon is individually overridable via tmux options.
-
Four themes:
auto,ascii,unicode,nerdfont - Built-in icons for 20+ apps including shells, agents, lazygit, yazi, vim, ssh, and more
- Override any icon with a single tmux option
Auto-mirroring
Open the sidebar once and it automatically appears in every window.
No need to toggle per-window. The sidebar follows you as you switch windows, keeping the tree visible wherever you work. The sidebar pane is created once and mirrored across all windows in the session.
Session management
Add windows and sessions, rename them, and close panes — all from the sidebar.
Manage your tmux workspace without leaving the sidebar. New items are inserted relative to your selection, keeping things contextual.
- aw to add a window (prompted for name)
- as to add a session
- rw / rs to rename windows and sessions
- x to close the selected pane (removing empty windows and sessions)
Jump history
Navigate through previously visited panes with Ctrl+o and Ctrl+i.
The jump list tracks your navigation. gg and G add sidebar targets, Ctrl+o jumps backward, Ctrl+i forward. The final backward jump returns focus to your original tmux pane. The list clears when focus leaves the sidebar.
Filter mode
Show only panes matching specific agents or commands.
Set a comma-separated filter list to show only matching panes. Press f to toggle filtering in real time. Matching checks pane command, title, and stored agent metadata.
set -g @tmux_pane_tree_filter "claude,codex,cursor"Context menus
Right-click or press m for contextual actions on
sessions, windows, and panes.
Context menus provide quick access to rename, close, reorder, and other actions depending on the selected row type. Works with mouse right-click or the m key for keyboard-only workflows.
Fully customizable
Width, colors, badges, shortcuts, and icon themes — configure everything via tmux options.
Override sidebar width, tree colors, badge icons, all
keybindings, icon themes, scroll offset, and more. Everything
is set via standard set -g tmux options.
- Custom hex colors for sessions, windows, and panes
- Override any badge icon or pane app icon
- Remap all 10+ sidebar shortcuts
- Conflict detection reverts to safe defaults automatically
Install
Get running in under a minute.
set -g @plugin 'sandudorogan/tmux-pane-tree'
Reload tmux, then press prefix + I to install.
git clone https://github.com/sandudorogan/tmux-pane-tree \
~/.config/tmux/plugins/tmux-pane-tree
# Source in your tmux.conf:
source-file ~/.config/tmux/plugins/tmux-pane-tree/tmux-pane-tree.tmux
# Reload:
tmux source-file ~/.tmux.conf# Via TPM option:
set -g @tmux_pane_tree_install_agent_hooks 1
# Or run the installer manually:
bash ~/.config/tmux/plugins/tmux-pane-tree/\
scripts/features/hooks/install-agent-hooks.shPatches Claude Code, Codex, Cursor, and OpenCode hook configs. Creates timestamped backups first.
Requires tmux 3.0+, Python 3, and bash 4.0+.
Keybindings
Navigate with your keyboard
Toggle & focus
| Key | Action |
|---|---|
prefix + t |
Toggle sidebar open / closed |
prefix + T |
Focus sidebar or return to main pane |
Navigation
| Key | Action |
|---|---|
j / Down |
Move selection down |
k / Up |
Move selection up |
gg |
Jump to top |
G |
Jump to bottom |
Ctrl+o |
Jump backward in history |
Ctrl+i |
Jump forward in history |
Enter |
Jump to selected pane |
q |
Close sidebar |
Ctrl+l |
Return focus to main pane |
Management
| Key | Action |
|---|---|
aw |
Add a window (prompts for name) |
as |
Add a session (prompts for name) |
rw |
Rename selected window |
rs |
Rename selected session |
f |
Toggle filter mode |
p |
Toggle hide-panes mode |
x |
Close selected pane |
m |
Open context menu |
All shortcuts are customizable via tmux options. See Configuration.
Configuration
Make it yours
Set options with set -g in your tmux config.
| Option | Default | Description |
|---|---|---|
@tmux_pane_tree_width |
25 |
Sidebar column width |
@tmux_pane_tree_focus_on_open |
1 |
Focus sidebar when toggled open |
@tmux_pane_tree_session_order |
— | Comma-separated session ordering |
@tmux_pane_tree_filter |
— | Comma-separated pane filter |
@tmux_pane_tree_hide_panes |
off |
Show only sessions and windows |
@tmux_pane_tree_scrolloff |
8 |
Cursor scroll margin |
@tmux_pane_tree_icon_theme |
auto |
auto, ascii,
unicode, nerdfont
|
@tmux_pane_tree_toggle_key |
t |
Tmux key to toggle sidebar |
@tmux_pane_tree_focus_key |
T |
Tmux key to focus sidebar |
@tmux_pane_tree_color_session |
— | Session name color (hex) |
@tmux_pane_tree_color_window |
— | Window name color (hex) |
@tmux_pane_tree_color_pane |
— | Pane name color (hex) |
@tmux_pane_tree_badge_running |
⏳ | Badge for running status |
@tmux_pane_tree_badge_needs_input |
❓ | Badge for needs-input status |
@tmux_pane_tree_badge_done |
✅ | Badge for done status |
@tmux_pane_tree_badge_error |
❌ | Badge for error status |
@tmux_pane_tree_install_agent_hooks |
0 |
Install agent hooks on plugin load |
Environment variables
| Variable | Description |
|---|---|
TMUX_PANE_TREE_STATE_DIR |
State file directory (default:
~/.local/state/tmux-sidebar)
|
TMUX_PANE_TREE_PLUGIN_DIR |
Override plugin root path |
TMUX_PANE_TREE_FONT_DIRS |
Path-separated list of font directories for auto-detect |
Custom shortcuts
set -g @tmux_pane_tree_add_window_shortcut zw # default: aw
set -g @tmux_pane_tree_add_session_shortcut zs # default: as
set -g @tmux_pane_tree_go_top_shortcut tt # default: gg
set -g @tmux_pane_tree_go_bottom_shortcut B # default: G
set -g @tmux_pane_tree_jump_back_shortcut C-p # default: C-o
set -g @tmux_pane_tree_jump_forward_shortcut C-n # default: C-i
set -g @tmux_pane_tree_rename_window_shortcut rw # default: rw
set -g @tmux_pane_tree_rename_session_shortcut rs # default: rs
set -g @tmux_pane_tree_toggle_filter_shortcut ff # default: f
set -g @tmux_pane_tree_close_pane_shortcut dd # default: x
If any shortcut is empty, duplicated, a prefix of another, or
contains the reserved q key, all ten revert to
defaults.
In action
What it looks like
Get started
Ready to try it?
Install with TPM or clone the repo. Your tmux sessions, organized in a persistent sidebar.