tmux window controller

Overview

• A tmux plugin for managing sessions and windows across your workspace.
• You can browse sessions, create/delete sessions, and move windows using only the keyboard.
• The popup UI is optimized for fast organization when you have multiple sessions.

Demo

Screencast.from.2026-02-17.22-08-11.webm

Installation

Using TPM

1. Add this to ~/.tmux.conf:

set -g @plugin 'arakkkkk/tmux-window-controller'

2. Run prefix + I inside tmux to install the plugin.

Manual installation

1. Place this repository at ~/.config/tmux/plugins/tmux-window-controller.
2. Add this to ~/.tmux.conf:

run-shell '~/.config/tmux/plugins/tmux-window-controller/tmux-window-controller.tmux'

3. Reload tmux:

tmux source-file ~/.tmux.conf

Usage

Configuration

# Launch key (default: w)
set -g @tmux_window_controller_key 'w'

# Session names to hide from the list (default: popup)
# Multiple names can be separated by commas or spaces.
set -g @tmux_window_controller_ignored_sessions 'popup,scratch'

# UI theme: solarized-dark (default) or solarized-light
set -g @tmux_window_controller_theme 'solarized-dark'

Default key bindings

• prefix + w: Open the UI
• h / l: Move session cursor
• j / k: Move window cursor
• J / K: Move the selected window down/up inside the current session
• H / L: Move the selected window to the previous/next session
• Ctrl-h / Ctrl-l: Swap the selected session with the previous/next session
• Enter: Focus the selected window
• r: Rename the selected session
• Ctrl-n: Create a new session
• Ctrl-d: Delete the selected session (with confirmation)
• q or Esc: Close the UI

Notes

• Session order changed by Ctrl-h / Ctrl-l is stored in @tmux_window_controller_session_order and reused on the next launch.

Technical specification

For detailed requirements, design notes, and acceptance criteria, see SPEC.md.