tmux-tree-sidebar

A persistent, clickable session → window tree sidebar for tmux.

Toggle it with a prefix key and a narrow pane pins to the left of your current window, showing every session and its windows as a two-level tree. Click a row (or press Enter) to switch there. The sidebar follows you across windows and sessions, and the current window stays highlighted.

It is powered by fzf running in a loop that never exits: selecting a row switches the client in place, then the list reloads and re-highlights wherever you landed.

  work                  ← session header (colored per session)
▸  11 editor            ← current window, marked with ▸
   12 server
  side
   21 logs

Contents

• Requirements
• Install
• Usage
• Configuration
• How it works
• Contributing
• License

Requirements

• tmux ≥ 3.2 (uses set-hook -a and pane-level user options)
• fzf

Install

With tpm, add to ~/.tmux.conf:

set -g @plugin 'keaising/tmux-tree-sidebar'

then press prefix + I to fetch the plugin. Reload tmux and press prefix + g to toggle the sidebar.

Manual install

git clone https://github.com/keaising/tmux-tree-sidebar ~/.tmux/plugins/tmux-tree-sidebar

Add to ~/.tmux.conf:

run-shell ~/.tmux/plugins/tmux-tree-sidebar/tree_sidebar.tmux

Usage

• prefix + g — toggle the sidebar on/off (the same key opens and closes it).
• Click a row, or move with the arrow keys / typing to filter, then Enter to switch to that session+window.
• A window left with nothing but the sidebar is closed automatically.

Configuration

All options are optional; defaults shown.

Option	Default	Description
@tree-sidebar-key	g	Prefix key that toggles the sidebar.
@tree-sidebar-width	30	Sidebar pane width in columns.
@tree-sidebar-hook-index	90	Index used for the tmux hooks that follow the user. Change it if it collides with another plugin's hooks.
@tree-sidebar-ignore	(empty)	Extended-regex of session names to hide. E.g. '^_|^scratch' hides sessions whose names start with _ or scratch.
@tree-sidebar-colors	Catppuccin Mocha	|-separated SGR color codes cycled per session. See below.

@tree-sidebar-width, @tree-sidebar-ignore, and @tree-sidebar-colors are read every time the sidebar renders, so changes take effect on the next toggle. @tree-sidebar-key and @tree-sidebar-hook-index are read once when the plugin loads, so after changing them restart the tmux server (tmux kill-server) to drop the old key binding and hooks.

Colors

@tree-sidebar-colors is a |-separated list of SGR color codes (the part between \033[ and m). Each session gets the next color, cycling. The default is the Catppuccin Mocha palette:

set -g @tree-sidebar-colors '38;2;250;179;135|38;2;166;227;161|38;2;203;166;247|38;2;116;199;236|38;2;243;139;168|38;2;249;226;175|38;2;148;226;213'

For 256-color terminals you can use simpler codes, e.g. '31|32|33|34|35|36' for the basic ANSI red/green/yellow/blue/magenta/cyan.

Example

set -g @plugin 'keaising/tmux-tree-sidebar'
set -g @tree-sidebar-key 'b'
set -g @tree-sidebar-width '24'
set -g @tree-sidebar-ignore '^_'

How it works

• A pane is marked as a sidebar with the pane-level option @is-tree-sidebar=1 (the fzf TUI overwrites pane_title, so that is not a reliable marker).
• tmux hooks (after-select-window, client-session-changed, window-linked) call an idempotent ensure script that splits a sidebar into the current window if one is missing. A mkdir lock serializes concurrent hook firings so a single switch never spawns duplicate sidebars.
• pane-exited and after-kill-pane both call a prune script that closes any window whose only remaining pane is the sidebar. Two hooks are needed because the last real pane can leave by its program exiting (pane-exited) or by being killed via kill-pane (after-kill-pane) — and kill-pane does not fire pane-exited, which is the path bind x kill-pane takes.

Contributing

Bug reports, ideas, and pull requests are welcome — see CONTRIBUTING.md. All scripts are kept ShellCheck-clean and the non-interactive paths are smoke-tested in CI across several tmux versions.

License

MIT © keaising