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

# Copy Mode

> Entering copy mode, vi/emacs key bindings, selecting and copying text in tmux

## Understanding Copy Mode

Copy mode allows you to navigate through a pane's history, search for text, and copy content to paste buffers. It's similar to a pager like `less` or a text editor's visual mode.

<Note>
  Copy mode provides access to the scrollback history, which by default stores 2000 lines. You can adjust this with the `history-limit` option.
</Note>

## Entering Copy Mode

### Basic Entry

```bash theme={null}
C-b [         # Enter copy mode
C-b PageUp    # Enter copy mode and scroll up one page
```

From the command line:

```bash theme={null}
tmux copy-mode

# Enter and scroll up one page
tmux copy-mode -u

# Enter and scroll down one page
tmux copy-mode -d

# Hide position indicator
tmux copy-mode -H

# Exit automatically when scrolling to bottom
tmux copy-mode -e
```

### Exit Copy Mode

Press `q` (vi mode) or `Escape` (emacs mode) to exit copy mode.

## Key Binding Modes

tmux supports two key binding sets for copy mode: **vi** and **emacs**. Set your preference with:

```bash theme={null}
# Use vi key bindings (default if VISUAL or EDITOR contains 'vi')
set-option -w mode-keys vi

# Use emacs key bindings
set-option -w mode-keys emacs
```

## Navigation in Copy Mode

### Vi Key Bindings

<Tabs>
  <Tab title="Basic Movement">
    | Key | Action                                 |
    | --- | -------------------------------------- |
    | `h` | Move cursor left                       |
    | `j` | Move cursor down                       |
    | `k` | Move cursor up                         |
    | `l` | Move cursor right                      |
    | `0` | Move to start of line                  |
    | `$` | Move to end of line                    |
    | `^` | Move to first non-whitespace character |
  </Tab>

  <Tab title="Word Movement">
    | Key | Action                                   |
    | --- | ---------------------------------------- |
    | `w` | Move to next word                        |
    | `b` | Move to previous word                    |
    | `e` | Move to end of next word                 |
    | `W` | Move to next space-separated word        |
    | `B` | Move to previous space-separated word    |
    | `E` | Move to end of next space-separated word |
  </Tab>

  <Tab title="Scrolling">
    | Key   | Action         |
    | ----- | -------------- |
    | `C-f` | Page down      |
    | `C-b` | Page up        |
    | `C-d` | Half page down |
    | `C-u` | Half page up   |
    | `C-e` | Scroll down    |
    | `C-y` | Scroll up      |
  </Tab>

  <Tab title="Jumping">
    | Key | Action                   |
    | --- | ------------------------ |
    | `g` | Go to top of history     |
    | `G` | Go to bottom of history  |
    | `:` | Prompt for line number   |
    | `H` | Move to top of screen    |
    | `M` | Move to middle of screen |
    | `L` | Move to bottom of screen |
  </Tab>
</Tabs>

### Emacs Key Bindings

<Tabs>
  <Tab title="Basic Movement">
    | Key     | Action                       |
    | ------- | ---------------------------- |
    | `Left`  | Move cursor left             |
    | `Down`  | Move cursor down             |
    | `Up`    | Move cursor up               |
    | `Right` | Move cursor right            |
    | `C-a`   | Move to start of line        |
    | `C-e`   | Move to end of line          |
    | `M-m`   | Move to first non-whitespace |
  </Tab>

  <Tab title="Word Movement">
    | Key   | Action                   |
    | ----- | ------------------------ |
    | `M-f` | Move to end of next word |
    | `M-b` | Move to previous word    |
  </Tab>

  <Tab title="Scrolling">
    | Key        | Action         |
    | ---------- | -------------- |
    | `PageDown` | Page down      |
    | `PageUp`   | Page up        |
    | `M-Down`   | Half page down |
    | `M-Up`     | Half page up   |
    | `C-Down`   | Scroll down    |
    | `C-Up`     | Scroll up      |
  </Tab>

  <Tab title="Jumping">
    | Key   | Action                   |
    | ----- | ------------------------ |
    | `M-<` | Go to top of history     |
    | `M->` | Go to bottom of history  |
    | `g`   | Prompt for line number   |
    | `M-R` | Move to top of screen    |
    | `M-r` | Move to middle of screen |
  </Tab>
</Tabs>

## Searching in Copy Mode

### Vi Mode Searching

```bash theme={null}
/pattern      # Search forward for pattern
?pattern      # Search backward for pattern
n             # Repeat last search forward
N             # Repeat last search backward
```

### Emacs Mode Searching

```bash theme={null}
C-s           # Incremental search forward
C-r           # Incremental search backward
n             # Repeat last search forward  
N             # Repeat last search backward
```

### Search Commands

From the tmux command prompt or key bindings:

```bash theme={null}
# Search forward
send-keys -X search-forward "error"

# Search backward
send-keys -X search-backward "warning"

# Search for plain text (not regex)
send-keys -X search-forward-text "literal text"

# Incremental search (with command-prompt -i)
command-prompt -i -p "Search:" \
  'send-keys -X search-forward-incremental "%%%"'
```

### Advanced Searching

<Note>
  Searches use regular expressions by default. For literal string matching, use the `-text` variants.
</Note>

## Selecting and Copying Text

### Vi Mode Selection

<Steps>
  ### Begin Selection

  ```bash theme={null}
  Space         # Begin selection (character mode)
  v             # Toggle rectangle selection
  V             # Select entire line
  ```

  ### Adjust Selection

  Move the cursor with navigation keys to extend the selection.

  ```bash theme={null}
  o             # Toggle which end of selection the cursor is at
  ```

  ### Copy Selection

  ```bash theme={null}
  Enter         # Copy selection and exit copy mode
  A             # Append to top buffer and exit
  ```
</Steps>

### Emacs Mode Selection

<Steps>
  ### Begin Selection

  ```bash theme={null}
  C-Space       # Begin selection
  R             # Toggle rectangle selection
  ```

  ### Adjust Selection

  Move with navigation keys to extend selection.

  ### Copy Selection

  ```bash theme={null}
  M-w           # Copy selection and exit copy mode
  C-g           # Clear selection without copying
  ```
</Steps>

### Copy Commands

Explicit copy commands for use with `send-keys -X`:

```bash theme={null}
# Copy selection
send-keys -X copy-selection
send-keys -X copy-selection-no-clear     # Don't clear selection
send-keys -X copy-selection-and-cancel   # Copy and exit

# Copy and pipe to command
send-keys -X copy-pipe "xclip -selection clipboard"
send-keys -X copy-pipe-and-cancel "pbcopy"

# Copy without selection
send-keys -X copy-line                    # Current line
send-keys -X copy-end-of-line             # From cursor to end

# Named buffers
send-keys -X copy-selection mybuffer      # Copy to named buffer
```

### Copy Flags

```bash theme={null}
# -C: Don't set terminal clipboard
# -P: Don't create paste buffer

# Copy to buffer only, not clipboard
send-keys -X copy-selection-and-cancel -C

# Copy to clipboard only, not buffer
send-keys -X copy-selection-and-cancel -P
```

## Selection Modes

Copy mode supports different selection modes:

### Character Selection (Default)

Select character by character.

```bash theme={null}
# Vi mode: Space to begin
# Emacs mode: C-Space to begin
```

### Line Selection

Select entire lines at a time.

```bash theme={null}
# Vi mode: V
send-keys -X select-line
```

### Rectangle Selection

Select a rectangular block of text.

```bash theme={null}
# Vi mode: v to toggle
# Emacs mode: R to toggle

send-keys -X rectangle-on
send-keys -X rectangle-off
send-keys -X rectangle-toggle
```

### Word Selection

Select word under cursor.

```bash theme={null}
send-keys -X select-word
```

## Jumping in Copy Mode

Quickly move within a line:

### Vi Mode Jumps

```bash theme={null}
f<char>       # Jump forward to next occurrence of <char>
F<char>       # Jump backward to previous occurrence of <char>
t<char>       # Jump forward to before next <char>
T<char>       # Jump backward to after previous <char>
;             # Repeat last jump
,             # Repeat last jump in reverse direction
```

Example:

```bash theme={null}
fa            # Jump to next 'a'
;             # Jump to next 'a' again
,             # Jump back to previous 'a'
```

### Jump Commands

```bash theme={null}
send-keys -X jump-forward "x"
send-keys -X jump-backward "x"
send-keys -X jump-to-forward "x"
send-keys -X jump-to-backward "x"
send-keys -X jump-again
send-keys -X jump-reverse
```

## Marks and Position

### Setting Marks

```bash theme={null}
# Vi mode: X
# Emacs mode: X
send-keys -X set-mark

# Jump to mark
M-x           # Both vi and emacs
send-keys -X jump-to-mark
```

### Position Indicator

The position indicator shows:

* Current cursor position
* Total lines in history
* Search match count (when searching)

```bash theme={null}
# Toggle position indicator visibility
P             # Both vi and emacs mode
send-keys -X toggle-position
```

## Advanced Copy Mode Features

### Scrolling Modes

```bash theme={null}
# Scroll to make current line top/middle/bottom
z             # Vi mode: middle
send-keys -X scroll-middle
send-keys -X scroll-top
send-keys -X scroll-bottom
```

### History Navigation

```bash theme={null}
# Move between shell prompts (requires shell support)
send-keys -X next-prompt
send-keys -X previous-prompt

# Move to command output start
send-keys -X next-prompt -o
```

<Note>
  Prompt navigation requires your shell to emit OSC 133 escape sequences. Supported by some shells with proper configuration.
</Note>

### Matching Brackets

```bash theme={null}
# Vi mode: %
# Emacs mode: M-C-f (forward), M-C-b (backward)
send-keys -X next-matching-bracket
send-keys -X previous-matching-bracket
```

### Paragraph Navigation

```bash theme={null}
# Vi mode: { and }
# Emacs mode: M-{ and M-}
send-keys -X previous-paragraph
send-keys -X next-paragraph
```

## Paste Buffers

Copied text is stored in paste buffers.

### Viewing Buffers

```bash theme={null}
C-b #         # List all paste buffers
C-b =         # Choose buffer interactively

tmux list-buffers
tmux lsb
```

### Pasting Buffers

```bash theme={null}
C-b ]         # Paste most recent buffer

tmux paste-buffer
tmux paste-buffer -b buffer0  # Paste specific buffer

# With separator
tmux paste-buffer -s ','      # Use comma as separator
tmux paste-buffer -r          # No replacement (keep LF)

# With bracketed paste
tmux paste-buffer -p
```

### Managing Buffers

```bash theme={null}
# Delete buffer
tmux delete-buffer -b buffer0

# Save buffer to file
tmux save-buffer ~/output.txt
tmux save-buffer -b buffer2 ~/backup.txt

# Load file into buffer
tmux load-buffer ~/input.txt
tmux load-buffer -b mybuffer ~/data.txt

# Set buffer from string
tmux set-buffer "some text"
tmux set-buffer -b mybuffer "more text"

# Append to buffer
tmux set-buffer -a "appended text"
```

## Mouse Support in Copy Mode

When mouse mode is enabled:

```bash theme={null}
# Enable mouse
set-option -g mouse on
```

Mouse actions in copy mode:

* **Click and drag** - Select text
* **Double-click** - Select word
* **Triple-click** - Select line
* **MouseDrag1** - Begin selection
* **MouseDragEnd1** - Copy selection and exit
* **WheelUp/Down** - Scroll history

### Mouse Copy Configuration

```bash theme={null}
# Copy on mouse drag end
bind-key -T copy-mode-vi MouseDragEnd1Pane \
  send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

bind-key -T copy-mode-emacs MouseDragEnd1Pane \
  send-keys -X copy-pipe-and-cancel "pbcopy"

# Don't exit on mouse drag end
bind-key -T copy-mode-vi MouseDragEnd1Pane \
  send-keys -X copy-pipe "xclip -selection clipboard"
```

## Customizing Copy Mode

### Custom Key Bindings

```bash theme={null}
# Vi mode key bindings
bind-key -T copy-mode-vi 'v' send-keys -X begin-selection
bind-key -T copy-mode-vi 'y' send-keys -X copy-selection-and-cancel
bind-key -T copy-mode-vi 'r' send-keys -X rectangle-toggle

# Emacs mode key bindings  
bind-key -T copy-mode 'v' send-keys -X begin-selection
bind-key -T copy-mode 'y' send-keys -X copy-selection-and-cancel
```

### Copy to System Clipboard

<Tabs>
  <Tab title="Linux (X11)">
    ```bash theme={null}
    # Vi mode
    bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
      'xclip -in -selection clipboard'

    # Emacs mode
    bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
      'xclip -in -selection clipboard'
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # Vi mode
    bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
      'pbcopy'

    # Emacs mode
    bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
      'pbcopy'
    ```
  </Tab>

  <Tab title="Wayland">
    ```bash theme={null}
    # Vi mode
    bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
      'wl-copy'

    # Emacs mode
    bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
      'wl-copy'
    ```
  </Tab>
</Tabs>

### Word Separators

Customize what characters are considered word boundaries:

```bash theme={null}
# Default separators
set-option -g word-separators " -_@"

# Only spaces
set-option -g word-separators " "

# No separators (treat everything as words)
set-option -g word-separators ""
```

## Copy Mode Commands Reference

### All Copy Mode Commands

Complete list of commands for `send-keys -X`:

<Accordion title="Movement Commands">
  ```bash theme={null}
  cursor-down
  cursor-left
  cursor-right
  cursor-up
  cursor-centre-vertical
  cursor-centre-horizontal
  start-of-line
  end-of-line
  back-to-indentation
  next-word
  next-word-end
  next-space
  next-space-end
  previous-word
  previous-space
  top-line
  middle-line
  bottom-line
  history-top
  history-bottom
  ```
</Accordion>

<Accordion title="Scrolling Commands">
  ```bash theme={null}
  halfpage-down
  halfpage-up
  page-down
  page-up
  scroll-down
  scroll-up
  scroll-middle
  scroll-top
  scroll-bottom
  ```
</Accordion>

<Accordion title="Search Commands">
  ```bash theme={null}
  search-forward <text>
  search-backward <text>
  search-forward-text <text>
  search-backward-text <text>
  search-forward-incremental <text>
  search-backward-incremental <text>
  search-again
  search-reverse
  ```
</Accordion>

<Accordion title="Selection Commands">
  ```bash theme={null}
  begin-selection
  clear-selection
  stop-selection
  select-line
  select-word
  rectangle-on
  rectangle-off
  rectangle-toggle
  other-end
  ```
</Accordion>

<Accordion title="Copy Commands">
  ```bash theme={null}
  copy-selection
  copy-selection-and-cancel
  copy-selection-no-clear
  append-selection
  append-selection-and-cancel
  copy-line
  copy-line-and-cancel
  copy-end-of-line
  copy-end-of-line-and-cancel
  copy-pipe <command>
  copy-pipe-and-cancel <command>
  copy-pipe-no-clear <command>
  ```
</Accordion>

<Accordion title="Other Commands">
  ```bash theme={null}
  cancel
  goto-line <line>
  jump-forward <char>
  jump-backward <char>
  jump-to-forward <char>
  jump-to-backward <char>
  jump-again
  jump-reverse
  jump-to-mark
  set-mark
  next-matching-bracket
  previous-matching-bracket
  next-paragraph
  previous-paragraph
  next-prompt
  previous-prompt
  refresh-from-pane
  toggle-position
  ```
</Accordion>

## Practical Examples

### Quick Clipboard Integration

```bash theme={null}
# Enter copy mode, select text, copy to clipboard
set-option -g mouse on
set-option -w mode-keys vi

bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel 'xclip -selection clipboard'
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel 'xclip -selection clipboard'

# Paste from clipboard
bind-key C-v run "xclip -selection clipboard -o | tmux load-buffer - ; tmux paste-buffer"
```

### Search and Copy Workflow

```bash theme={null}
# 1. Enter copy mode
C-b [

# 2. Search for text
/error

# 3. Navigate to desired match
n     # Next match
N     # Previous match

# 4. Begin selection
Space

# 5. Extend selection
l l l  # Move right

# 6. Copy
Enter

# 7. Paste elsewhere
C-b ]
```

### Copy Command Output

```bash theme={null}
# Run command and copy output
bind-key C-c run-shell \
  'tmux capture-pane -p | tail -n 20 | xclip -selection clipboard'

# Copy entire pane history
bind-key C-h run-shell \
  'tmux capture-pane -pS -32768 | xclip -selection clipboard'
```

### Incremental Search Setup

```bash theme={null}
# Vi mode incremental search
bind-key -T copy-mode-vi / command-prompt -i -p "Search:" \
  'send-keys -X search-forward-incremental "%%%"'
  
bind-key -T copy-mode-vi ? command-prompt -i -p "Search:" \
  'send-keys -X search-backward-incremental "%%%"'
```