# tmux Quick Reference

*Sessions, windows, panes, copy mode, configuration*

> Source: tmux Documentation (github.com/tmux/tmux) · MIT

## Session Management

### Creating & Attaching

```
tmux                        # new session
tmux new -s work            # new named session
tmux attach -t work         # attach to session
tmux attach -dt work        # detach others, attach
```

### Session Commands

| Command | Description |
|---------|-------------|
| `tmux ls` | List all sessions |
| `tmux kill-session -t work` | Kill a named session |
| `tmux kill-server` | Kill the tmux server and all sessions |
| `tmux rename-session -t old new` | Rename a session |
| `Prefix d` | Detach from current session |
| `Prefix $` | Rename current session |
| `Prefix s` | List sessions (interactive) |

*Default prefix is Ctrl-b*

## Windows

### Window Key Bindings

| Command | Description |
|---------|-------------|
| `Prefix c` | Create new window |
| `Prefix ,` | Rename current window |
| `Prefix &` | Close current window (confirm) |
| `Prefix n` | Next window |
| `Prefix p` | Previous window |
| `Prefix 0-9` | Switch to window by number |
| `Prefix w` | List windows (interactive picker) |
| `Prefix l` | Toggle to last active window |

### Window Commands

```
tmux new-window -t work     # new window in session
tmux swap-window -t 0       # move window to index 0
tmux move-window -t 3       # renumber to index 3
```

## Panes

### Splitting & Closing

| Command | Description |
|---------|-------------|
| `Prefix %` | Split horizontally (left \| right) |
| `Prefix "` | Split vertically (top / bottom) |
| `Prefix x` | Close current pane (confirm) |
| `Prefix !` | Break pane into its own window |
| `Prefix z` | Toggle pane zoom (full window) |

### Resizing Panes

| Command | Description |
|---------|-------------|
| `Prefix Ctrl-Arrow` | Resize by 1 cell |
| `Prefix Alt-Arrow` | Resize by 5 cells |
| `Prefix Space` | Cycle through layouts |

*Layouts: even-horizontal, even-vertical, main-horizontal, main-vertical, tiled*

## Navigation

### Moving Between Panes

| Command | Description |
|---------|-------------|
| `Prefix Arrow` | Move to pane in direction |
| `Prefix o` | Cycle to next pane |
| `Prefix q` | Show pane numbers, then press number to jump |
| `Prefix {` | Swap pane with previous |
| `Prefix }` | Swap pane with next |

### Moving Between Sessions

| Command | Description |
|---------|-------------|
| `Prefix (` | Switch to previous session |
| `Prefix )` | Switch to next session |
| `Prefix s` | Session picker (tree view) |
| `Prefix w` | Window picker across all sessions |

## Copy Mode

### Entering & Navigating

| Command | Description |
|---------|-------------|
| `Prefix [` | Enter copy mode |
| `q` | Exit copy mode |
| `Arrow / hjkl` | Move cursor (vi mode) |
| `Ctrl-u / Ctrl-d` | Page up / page down |
| `g / G` | Jump to top / bottom |
| `/` | Search forward |
| `?` | Search backward |
| `n / N` | Next / previous search match |

### Selecting & Copying

| Command | Description |
|---------|-------------|
| `Space` | Start selection (vi mode) |
| `Enter` | Copy selection and exit |
| `Prefix ]` | Paste buffer |
| `v` | Toggle rectangle selection (vi mode) |

*Enable vi mode: set -g mode-keys vi*

## Configuration

### Common Settings (~/.tmux.conf)

```
set -g mouse on                 # enable mouse
set -g base-index 1             # windows start at 1
set -g renumber-windows on      # renumber on close
set -g default-terminal "tmux-256color"
set -g history-limit 50000
```

### Reload Config

```
tmux source-file ~/.tmux.conf   # from shell
# or Prefix : then type:
source-file ~/.tmux.conf
```

## Status Bar

### Status Bar Options

```
set -g status-position top
set -g status-style "bg=black,fg=white"
set -g status-left "[#S] "
set -g status-right "%H:%M %d-%b"
set -g status-interval 5
```

### Format Variables

| Command | Description |
|---------|-------------|
| `#S` | Session name |
| `#I` | Window index |
| `#W` | Window name |
| `#P` | Pane index |
| `#H` | Hostname |
| `#T` | Pane title |

## Key Bindings

### Custom Bindings

```
# change prefix to Ctrl-a
unbind C-b
set -g prefix C-a
bind C-a send-prefix
# vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
```

### Binding Syntax

| Command | Description |
|---------|-------------|
| `bind X command` | Bind Prefix + X to command |
| `bind -n M-Left prev` | Bind without prefix (Alt-Left) |
| `bind -r H resize-pane -L 5` | Repeatable binding |
| `unbind X` | Remove a binding |
| `Prefix ?` | List all current key bindings |

## Scripting

### Scripted Layouts

```
tmux new-session -d -s dev
tmux send-keys -t dev "vim" Enter
tmux split-window -h -t dev
tmux send-keys -t dev "npm run dev" Enter
tmux attach -t dev
```

### Useful Commands

| Command | Description |
|---------|-------------|
| `tmux send-keys -t sess 'cmd' Enter` | Send keystrokes to a session |
| `tmux capture-pane -p` | Print pane contents to stdout |
| `tmux display-message '#S'` | Show a message / variable |
| `tmux set-environment -g VAR val` | Set an environment variable |
| `tmux list-keys` | List all key bindings |

## Common Patterns

### Recommended ~/.tmux.conf

```
set -g mouse on
set -g base-index 1
set -g mode-keys vi
set -g status-position top
set -g history-limit 50000
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
```

### Quick Recipes

| Command | Description |
|---------|-------------|
| `Survive SSH disconnect` | `tmux new -s work` → disconnect → `tmux attach -t work` |
| `Share session` | Both users `tmux attach -t same` (read-only: `-r`) |
| `Save scrollback` | `tmux capture-pane -S -3000 -p > log.txt` |
| `Kill stuck pane` | Prefix x, or `tmux kill-pane -t %N` |
| `Reorder windows` | `:swap-window -s 3 -t 1` |