tmux

What this skill does

# 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:

```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
tmux list-sessions
# or
tmux ls
```

**Attach to session:**
```bash
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:**
```bash
tmux kill-session -t session-name
```

### Window Management

**Create new window:**
```bash
# 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:**
```bash
# 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:**
```bash
tmux select-window -t session-name:window-number
```

**List windows:**
```bash
tmux list-windows -t session-name
```

**Swap windows:**
```bash
# 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:**
```bash
# 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:**
```bash
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`:

```bash
# 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:**

```bash
# 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

```bash
# 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:**
```bash
tmux new-session -s "workflow-name" -d
```

**2. Create windows for each task:**
```bash
tmux new-window -t workflow-name:1 -n "window-name"
```

**3. Send commands to windows:**
```bash
tmux send-keys -t workflow-name:1 "command" C-m
```

**4. Select starting window:**
```bash
tmux select-window -t workflow-name:0
```

**5. Attach to session:**
```bash
tmux attach-session -t workflow-name
```

**Complete example workflow:**
```bash
# Create