tmux Terminal Multiplexer Skill

This skill provides guidance for working with tmux, a terminal multiplexer that enables multiple terminal sessions, windows, and panes within a single terminal window.

When to Use This Skill

Use this skill when:

• Creating or managing tmux sessions, windows, or panes

• Configuring tmux keybindings or settings in ~/.tmux.conf

• Building workflows that leverage tmux for multi-file review or parallel tasks

• Troubleshooting tmux configuration issues

• Setting up custom tmux-based tools or functions

User's tmux Configuration

The user has a custom tmux configuration at ~/.tmux.conf with ergonomic keybindings optimized for file review workflows.

Custom Keybindings

Easy Window Navigation:

• Option+] or Ctrl+Shift+]

• Next window

• Option+[ or Ctrl+Shift+[

• Previous window

• Option+{

• Move current window left

• Option+}

• Move current window right

Direct Window Jumping:

• Option+0 through Option+9
• Jump directly to window 0-9

Pane Switching:

• Option+Left/Right/Up/Down
• Navigate between panes

Synchronization:

• Ctrl-b e
• Toggle pane synchronization (send commands to all panes)

Standard tmux Keys (still available):

• Ctrl-b n

• Next window

• Ctrl-b p

• Previous window

• Ctrl-b w

• List all windows (visual selector)

• Ctrl-b d

• Detach from session

• Ctrl-b c

• Create new window

• Ctrl-b ,

• Rename current window

• Ctrl-b &

• Kill current window

• Ctrl-b x

• Kill current pane

• Ctrl-b "

• Split pane horizontally

• Ctrl-b %

• Split pane vertically

Configuration Features

The user's ~/.tmux.conf includes:

Mouse support enabled for scrolling and pane selection

set -g mouse on

Pane border status showing index and running command

set -g pane-border-status top set -g pane-border-format " #{pane_index} #{pane_current_command} "

Custom tmux Workflows

tmux-review Function

The user has a custom tmux-review shell function in ~/.zsh/claude-managed.zshrc for reviewing multiple files with glow markdown rendering.

Usage:

tmux-review file1.md file2.sh file3.txt [... more files]

Features:

• Opens each file in a separate tmux window using glow for rendering

• Creates a helper window (window 0) with navigation instructions

• Generates unique session names with timestamps: review-$(date +%s)

• Validates all files exist before starting

• Helper text dynamically generated at /tmp/tmux-review-helper.md

• Window names use truncated filenames (max 20 chars)

Example:

Review S3 bucket analysis files

tmux-review compliant-buckets.md non-compliant-buckets.md remediation.sh jira-update.md

This creates a tmux session with:

• Window 0: Helper text with navigation instructions

• Window 1: compliant-buckets.md (rendered with glow)

• Window 2: non-compliant-buckets.md (rendered with glow)

• Window 3: remediation.sh (rendered with glow)

• Window 4: jira-update.md (rendered with glow)

Navigate between files using Option+] / Option+[ or Ctrl+Shift+] / Ctrl+Shift+[ .

Common tmux Operations

Session Management

Create new session:

Basic session

tmux new-session -s session-name

Detached session (create without attaching)

tmux new-session -s session-name -d

Named session with initial window name

tmux new-session -s session-name -n window-name

List sessions:

tmux list-sessions

or

tmux ls

Attach to session:

tmux attach-session -t session-name

or short form

tmux attach -t session-name

or even shorter

tmux a -t session-name

Detach from session:

• Press Ctrl-b d inside tmux

• Session keeps running in background

Kill session:

tmux kill-session -t session-name

Window Management

Create new window:

Create window with name

tmux new-window -t session-name:window-number -n window-name

Create window and run command

tmux new-window -t session-name:1 -n "logs" "tail -f /var/log/app.log"

Send commands to window:

Send command and execute (C-m = Enter)

tmux send-keys -t session-name:window-number "command" C-m

Example: Open file with glow in window 1

tmux send-keys -t myreview:1 "glow README.md" C-m

Select window:

tmux select-window -t session-name:window-number

List windows:

tmux list-windows -t session-name

Swap windows:

Swap current window with next

tmux swap-window -t +1

Swap current window with previous

tmux swap-window -t -1

Pane Management

Split pane horizontally:

• Ctrl-b " (creates pane below)

Split pane vertically:

• Ctrl-b % (creates pane to the right)

Navigate panes:

• Use Option+Arrow keys (user's custom config)

• Or Ctrl-b followed by arrow keys

Resize panes:

From command mode (Ctrl-b :)

resize-pane -D 5 # Down by 5 lines resize-pane -U 5 # Up by 5 lines resize-pane -L 5 # Left by 5 columns resize-pane -R 5 # Right by 5 columns

Synchronize panes:

• Press Ctrl-b e to toggle (user's custom binding)

• All panes receive the same input when synchronized

• Useful for running commands on multiple servers

Kill pane:

• Ctrl-b x then confirm with y

Configuration Management

Reload Configuration

After editing ~/.tmux.conf , reload it without restarting tmux:

From shell:

tmux source-file ~/.tmux.conf

From within tmux: Press Ctrl-b : then type:

source-file ~/.tmux.conf

Adding New Keybindings

Keybinding syntax in ~/.tmux.conf :

Prefix-based binding (requires Ctrl-b first)

bind key-name command

No-prefix binding (direct keypress)

bind -n key-name command

Example prefix binding: Ctrl-b r to reload config

bind r source-file ~/.tmux.conf ; display "Config reloaded!"

Example no-prefix: Option+h to split horizontally

bind -n M-h split-window -h

Key notation:

• M- prefix = Option/Alt key (e.g., M-[ = Option+[)

• C- prefix = Control key (e.g., C-b = Ctrl+b)

• S- prefix = Shift key (e.g., C-S-[ = Ctrl+Shift+[)

• Special keys: Left , Right , Up , Down , Enter , etc.

• Brackets need quoting: bind -n "C-S-[" previous-window

Common binding patterns:

Window navigation

bind -n M-] next-window bind -n M-[ previous-window

Pane navigation

bind -n M-Left select-pane -L bind -n M-Right select-pane -R

Window jumping

bind -n M-1 select-window -t 1 bind -n M-2 select-window -t 2

Toggle feature

bind e setw synchronize-panes

Common Configuration Options

Enable mouse support (scroll, select panes, resize)

set -g mouse on

Set default shell

set -g default-shell /bin/zsh

Set scrollback buffer size

set -g history-limit 10000

Start window numbering at 1 instead of 0

set -g base-index 1

Start pane numbering at 1 instead of 0

setw -g pane-base-index 1

Renumber windows when one is closed

set -g renumber-windows on

Set status bar position

set -g status-position top # or bottom

Status bar styling

set -g status-bg black set -g status-fg white set -g status-left '[#S] ' set -g status-right '%H:%M %d-%b-%y'

Pane border styling

set -g pane-border-status top set -g pane-border-format " #{pane_index} #{pane_current_command} " set -g pane-border-style fg=colour240 set -g pane-active-border-style fg=colour33

Creating tmux-Based Workflows

When building custom tmux workflows (like tmux-review ), follow this pattern:

1. Create session with descriptive name:

tmux new-session -s "workflow-name" -d

2. Create windows for each task:

tmux new-window -t workflow-name:1 -n "window-name"

3. Send commands to windows:

tmux send-keys -t workflow-name:1 "command" C-m

4. Select starting window:

tmux select-window -t workflow-name:0

5. Attach to session:

tmux attach-session -t workflow-name

Complete example workflow:

Create a code review session

review_code() { local session="code-review-$(date +%s)"

Create session with helper window

tmux new-session -s "$session" -d -n "helper" tmux send-keys -t "$session:0" "cat review-checklist.md" C-m

Window 1: Main code

tmux new-window -t "$session:1" -n "main" tmux send-keys -t "$session:1" "vim src/main.py" C-m

Window 2: Tests

tmux new-window -t "$session:2" -n "tests" tmux send-keys -t "$session:2" "vim tests/test_main.py" C-m

Window 3: Run tests

tmux new-window -t "$session:3" -n "pytest" tmux send-keys -t "$session:3" "pytest -v" C-m

Start at helper window

tmux select-window -t "$session:0" tmux attach-session -t "$session" }

Troubleshooting

Syntax Errors in Configuration

Common issues:

Escaped semicolons: Use space before ; in command chains

Correct

bind r source-file ~/.tmux.conf ; display "Reloaded"

Incorrect

bind r source-file ~/.tmux.conf; display "Reloaded"

Special characters in keybindings: Quote brackets and special chars

Correct

bind -n "C-S-[" previous-window

May fail

bind -n C-S-[ previous-window

Invalid key names: Check tmux version compatibility

tmux -V # Check version

Session Not Found

If tmux attach fails:

List all sessions to find correct name

tmux ls

Create new session if none exists

tmux new-session -s session-name

Configuration Not Loading

Verify configuration file exists:

ls -la ~/.tmux.conf

Check for syntax errors:

This will show syntax errors if any exist

tmux source-file ~/.tmux.conf

View current tmux configuration:

Show all current settings

tmux show-options -g

Show all current keybindings

tmux list-keys

Keybindings Not Working

Check if keybinding conflicts with terminal emulator:

• Some terminals intercept Ctrl+Shift+[ before tmux sees it

• Test with Option+[ alternative

• Use tmux list-keys to verify bindings are registered

Check if you're in a nested tmux session:

From inside tmux

echo $TMUX

If this shows a value, you're in tmux

Self-Test

To verify this skill is working correctly:

Check tmux installation and version:

tmux -V

Expected: tmux 3.5a or similar

Verify user's configuration exists:

cat ~/.tmux.conf

Expected: Should show custom keybindings

Test the tmux-review function exists:

type tmux-review

Expected: Should show function definition

Create and test a session:

tmux new-session -s test -d tmux ls | grep test tmux kill-session -t test

Expected: Session appears in list, then is removed

All commands should execute without errors.