> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tmux/tmux/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Bindings

> Configure custom key bindings and understand default tmux shortcuts

Key bindings in tmux allow you to execute commands with keyboard shortcuts. Bindings can be customized to fit your workflow and are organized into key tables.

## Key Binding Commands

### bind-key

Create or modify key bindings:

```bash theme={null}
bind [-nr] [-T key-table] [-N note] key command [arguments]
```

**Flags**:

* `-n`: Bind without requiring the prefix key (root table)
* `-r`: Allow key to repeat without pressing prefix again
* `-T`: Specify the key table (default: prefix)
* `-N`: Add a descriptive note for the binding

**Examples**:

```bash theme={null}
# Bind prefix + r to reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded"

# Bind without prefix
bind -n C-Left previous-window

# Repeatable binding
bind -r C-Up resize-pane -U

# With descriptive note
bind -N "Reload configuration" r source-file ~/.tmux.conf
```

The `bind-key` command is implemented in cmd-bind-key.c:54-107 and uses the `key_bindings_add()` function to register bindings.

### unbind-key

Remove key bindings:

```bash theme={null}
unbind [-n] [-T key-table] key
```

**Example**:

```bash theme={null}
# Remove default C-b binding
unbind C-b

# Remove from root table
unbind -n MouseDrag1Pane
```

### list-keys

List all key bindings:

```bash theme={null}
list-keys [-1] [-N] [-T key-table] [key]
```

**Flags**:

* `-1`: Show only one binding
* `-N`: Show notes/descriptions
* `-T`: Filter by key table

## Key Tables

Key bindings are organized into tables. From key-bindings.c:104-123, tmux uses a red-black tree structure to manage key tables efficiently.

### Built-in Key Tables

| Table          | Purpose                                        |
| -------------- | ---------------------------------------------- |
| `prefix`       | Default key table, accessed after prefix key   |
| `root`         | Keys that work without prefix (with `-n` flag) |
| `copy-mode`    | Keys active in copy mode (emacs style)         |
| `copy-mode-vi` | Keys active in copy mode (vi style)            |

### Using Key Tables

```bash theme={null}
# Bind in prefix table (default)
bind x kill-pane

# Bind in root table
bind -n C-Left select-pane -L

# Bind in copy mode table
bind -Tcopy-mode C-c send -X cancel
```

## Default Key Bindings

tmux initializes default bindings in `key_bindings_init()` (key-bindings.c:347-669). Here are the most important defaults:

### Session Management

```bash theme={null}
# Key bindings from key-bindings.c:352-409
bind C-z { suspend-client }            # Suspend client
bind d { detach-client }                # Detach client  
bind L { switch-client -l }             # Last client
bind s { choose-tree -Zs }             # Choose session
bind $ { command-prompt -I'#S' { rename-session -- '%%' } }
```

### Window Management

```bash theme={null}
# Key bindings from key-bindings.c:369-403
bind c { new-window }                   # Create window
bind n { next-window }                  # Next window
bind p { previous-window }              # Previous window
bind l { last-window }                  # Last window
bind w { choose-tree -Zw }             # Choose window
bind & { confirm-before -p"kill-window #W? (y/n)" kill-window }
bind , { command-prompt -I'#W' { rename-window -- '%%' } }
bind . { command-prompt -T target { move-window -t '%%' } }

# Select windows by number
bind 0 { select-window -t:=0 }
bind 1 { select-window -t:=1 }
# ... bindings for 2-9
```

### Pane Management

```bash theme={null}
# Key bindings from key-bindings.c:356-413
bind '"' { split-window }               # Split vertically
bind % { split-window -h }              # Split horizontally
bind o { select-pane -t:.+ }           # Next pane
bind x { confirm-before -p"kill-pane #P? (y/n)" kill-pane }
bind z { resize-pane -Z }              # Zoom pane
bind ! { break-pane }                  # Break to new window

# Pane navigation
bind -r Up { select-pane -U }
bind -r Down { select-pane -D }
bind -r Left { select-pane -L }
bind -r Right { select-pane -R }

# Pane resizing (repeatable)
bind -r C-Up { resize-pane -U }
bind -r C-Down { resize-pane -D }
bind -r C-Left { resize-pane -L }
bind -r C-Right { resize-pane -R }

# By 5 cells
bind -r M-Up { resize-pane -U 5 }
bind -r M-Down { resize-pane -D 5 }
bind -r M-Left { resize-pane -L 5 }
bind -r M-Right { resize-pane -R 5 }

# Swap panes
bind '{' { swap-pane -U }
bind '}' { swap-pane -D }
```

### Layout Management

```bash theme={null}
# Key bindings from key-bindings.c:414-420
bind Space { next-layout }              # Cycle layouts
bind M-1 { select-layout even-horizontal }
bind M-2 { select-layout even-vertical }
bind M-3 { select-layout main-horizontal }
bind M-4 { select-layout main-vertical }
bind M-5 { select-layout tiled }
```

### Copy Mode

```bash theme={null}
# Key bindings from key-bindings.c:387-409
bind [ { copy-mode }                    # Enter copy mode
bind PPage { copy-mode -u }            # Enter and scroll up
bind ] { paste-buffer -p }             # Paste buffer
bind = { choose-buffer -Z }            # Choose buffer
bind '#' { list-buffers }              # List buffers
bind - { delete-buffer }               # Delete most recent buffer
```

### Copy Mode Keys (Emacs)

```bash theme={null}
# Key bindings from key-bindings.c:491-565
bind -Tcopy-mode C-Space { send -X begin-selection }
bind -Tcopy-mode C-w { send -X copy-pipe-and-cancel }
bind -Tcopy-mode M-w { send -X copy-pipe-and-cancel }
bind -Tcopy-mode C-n { send -X cursor-down }
bind -Tcopy-mode C-p { send -X cursor-up }
bind -Tcopy-mode C-v { send -X page-down }
bind -Tcopy-mode M-v { send -X page-up }
```

### Copy Mode Keys (Vi)

```bash theme={null}
# Key bindings from key-bindings.c:567-654
bind -Tcopy-mode-vi v { send -X rectangle-toggle }
bind -Tcopy-mode-vi Space { send -X begin-selection }
bind -Tcopy-mode-vi Enter { send -X copy-pipe-and-cancel }
bind -Tcopy-mode-vi h { send -X cursor-left }
bind -Tcopy-mode-vi j { send -X cursor-down }
bind -Tcopy-mode-vi k { send -X cursor-up }
bind -Tcopy-mode-vi l { send -X cursor-right }
```

## Mouse Bindings

tmux includes comprehensive mouse support (key-bindings.c:442-489):

```bash theme={null}
# Mouse button 1 on pane
bind -n MouseDown1Pane { select-pane -t=; send -M }

# Mouse drag in pane
bind -n MouseDrag1Pane { 
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { copy-mode -M } 
}

# Mouse wheel
bind -n WheelUpPane { 
  if -F '#{||:#{alternate_on},#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { copy-mode -e } 
}

# Mouse button 2 (middle click) - paste
bind -n MouseDown2Pane { 
  select-pane -t=; 
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { paste -p } 
}

# Double click - select word
bind -n DoubleClick1Pane {
  select-pane -t=;
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}'
    { send -M }
    { copy-mode -H; send -X select-word; run -d0.3; send -X copy-pipe-and-cancel }
}

# Triple click - select line
bind -n TripleClick1Pane {
  select-pane -t=;
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}'
    { send -M }
    { copy-mode -H; send -X select-line; run -d0.3; send -X copy-pipe-and-cancel }
}
```

## Custom Binding Examples

Here are practical custom bindings from example\_tmux.conf:

### Function Key Bindings

```bash theme={null}
# Select higher numbered windows with function keys
bind F1 selectw -t:10
bind F2 selectw -t:11
bind F3 selectw -t:12
# ... F4 through F12 for windows 13-21
```

### Toggle Bindings

```bash theme={null}
# Toggle window size between smallest and largest
bind F set -w window-size

# Toggle monitoring activity
bind m set monitor-activity

# Toggle synchronize-panes with status message
bind y set synchronize-panes\; display 'synchronize-panes #{?synchronize-panes,on,off}'
```

### Prefix Key Customization

```bash theme={null}
# Change prefix from C-b to C-a
set -g prefix C-a
unbind C-b
bind C-a send-prefix
```

## Key Codes

Keys can be specified in several formats:

| Format    | Example                    | Description          |
| --------- | -------------------------- | -------------------- |
| Character | `x`                        | Single character     |
| Control   | `C-x`                      | Control + character  |
| Meta/Alt  | `M-x`                      | Meta/Alt + character |
| Shift     | `S-Up`                     | Shift + key          |
| Function  | `F1-F12`                   | Function keys        |
| Special   | `Space`, `Enter`, `Escape` | Special keys         |
| Mouse     | `MouseDown1Pane`           | Mouse events         |

## Repeatable Bindings

The `-r` flag creates repeatable bindings. After pressing the binding once, you can press just the key (without prefix) within the `repeat-time` window:

```bash theme={null}
# Set repeat time to 1 second
set -g repeat-time 1000

# Repeatable pane resizing
bind -r Up resize-pane -U
bind -r Down resize-pane -D

# Now: prefix + Up, Up, Up (without prefix)
```

From key-bindings.c:222-223, repeatable bindings are marked with the `KEY_BINDING_REPEAT` flag.

## Listing and Describing Keys

```bash theme={null}
# List all bindings
tmux list-keys

# List bindings with descriptions
tmux list-keys -N

# List bindings in specific table
tmux list-keys -T copy-mode-vi

# Describe a specific key
tmux list-keys -1N C-b
```

## Binding Best Practices

<Accordion title="Avoid conflicts with shell/editor">
  Don't bind keys that conflict with your shell or text editor. For example, `C-s` is used by shell flow control.
</Accordion>

<Accordion title="Use meaningful mnemonics">
  Choose key bindings that are easy to remember. For example, `r` for reload, `|` for vertical split.
</Accordion>

<Accordion title="Document your bindings">
  Use the `-N` flag to add notes to your custom bindings:

  ```bash theme={null}
  bind -N "Split pane vertically" | split-window -h
  ```
</Accordion>

<Accordion title="Group related bindings">
  Keep related bindings together in your config file for easier maintenance.
</Accordion>

<Warning>
  Changing key bindings doesn't affect existing sessions until you reload the configuration or restart tmux.
</Warning>