# Copy mode and screenshots

URL: https://tuios.dev/docs/keybindings/copy-mode

> Copy mode and screenshots: part of the Keybindings of TUIOS.

This page is one part of `docs/KEYBINDINGS.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/KEYBINDINGS.md). The [Keybindings](https://tuios.dev/docs/keybindings) page lists every part.

## Copy mode

`Ctrl+B [` starts copy mode on the focused pane. The copy cursor starts on the
terminal cursor, which is usually the prompt line. tmux does the same. To start
in the middle row, set `appearance.selection.copy_entry` to `center`.

| Key                        | Action                                                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/`                        | Search forward, down to the newest output                                                                                                                                 |
| `?`                        | Search backward, up into the scrollback                                                                                                                                   |
| `n`                        | Go to the next match in the direction of the last search                                                                                                                  |
| `N`                        | Go to the next match in the opposite direction                                                                                                                            |
| `Esc` in the search prompt | Cancel the search and move the cursor back                                                                                                                                |
| `v`                        | Start a character selection                                                                                                                                               |
| `V`                        | Start a line selection                                                                                                                                                    |
| `Ctrl+V`                   | Start a block selection. In a block selection, end the selection                                                                                                          |
| `o`                        | Go to the other end of the selection. In a block selection, go to the opposite corner                                                                                     |
| `q` or `Esc`               | Leave copy mode. In a selection, `Esc` and `q` only end the selection                                                                                                     |
| `Enter`                    | Leave copy mode. In a selection, copy the selection, then leave. In the search prompt, `Enter` runs the search. The action is `copy_mode_exit` in the `copy_mode` section |
| `Ctrl+C`                   | Leave copy mode from normal mode, a selection, the search prompt or `f`/`t`. Nothing is copied                                                                            |

A block selection is a rectangle. The cursor is one corner, and every motion
moves that corner. `y` writes one line for each row, with a newline between
rows. A row stops at its last printed character, so a short row is not padded
to the right edge. Blanks inside a row stay when the row has text after them. A
wide character on an edge of the block is copied whole. A wrapped line copies
as one line for each row on the screen. `copy_command` and the copy pipe keys
get the same text.

The prompt shows `/` or `?` to show the direction. The search starts at the
copy cursor. When no match is found in that direction, the search continues
from the other end of the buffer. `n` and `N` start at the copy cursor, so they
find the nearest match after you move the cursor.

Two actions start copy mode and open the search prompt with one key:

| Action                      | Key  |
| --------------------------- | ---- |
| `copy_mode_search_forward`  | None |
| `copy_mode_search_backward` | None |

They are the same as tmux `bind-key b copy-mode \; send-keys ?`. They have no
default key. Bind one in any section. This example uses `Ctrl+B /`:

```toml
[keybindings.prefix_mode]
copy_mode_search_backward = ["/"]
```

The command palette also has the entries "Copy mode: search forward" and
"Copy mode: search backward". If the pane is already in copy mode, the action
opens the prompt and does not move the cursor. In multi copy mode, the prompt
opens in each pane of the mode.

In copy mode, a key in the `global`, `terminal_mode` or `window_management`
section starts the action. A key under the leader does not start it, because
copy mode uses `Ctrl+B` for page up. In copy mode, `/` and `?` open the same
prompts.

When a search finds more than 1000 matches, the prompt shows `1000+`.

### Focus keys in copy mode

The `terminal_focus_left`, `terminal_focus_right`, `focus_up` and
`focus_down` keys also work in copy mode. In window mode, the
window-mode focus keys work. Focus moves to the next pane. The old pane stays
in copy mode, as in tmux. When you go back to it, the copy cursor is where you
left it.

A focus key that copy mode also uses keeps its copy mode action. For example,
`h` moves the copy cursor, and `alt+left` moves focus. This example binds
`alt+h` and `alt+l` as in tmux:

```toml
[keybindings.terminal_mode]
terminal_focus_left = ["alt+h"]
terminal_focus_right = ["alt+l"]
```

A key under the leader does not work in copy mode, because copy mode uses
`Ctrl+B` for page up. `Ctrl+B` and then an arrow key does not move focus there.

### Motions

The cursor motions are bindings in the `copy_mode` section. In a `v`, `V` or
`Ctrl+V` selection they move the end of the selection. A count typed before
the key repeats a motion that steps, such as `3j`, in a selection too. `10G`
goes to line 10.

| Action                                                                                | Default key                                   |
| ------------------------------------------------------------------------------------- | --------------------------------------------- |
| `copy_mode_left`, `copy_mode_down`, `copy_mode_up`, `copy_mode_right`                 | `h` `Left`, `j` `Down`, `k` `Up`, `l` `Right` |
| `copy_mode_word_end`                                                                  | `e`                                           |
| `copy_mode_big_word_forward`, `copy_mode_big_word_backward`, `copy_mode_big_word_end` | `W`, `B`, `E`                                 |
| `copy_mode_half_page_up`, `copy_mode_half_page_down`                                  | `Ctrl+U`, `Ctrl+D`                            |
| `copy_mode_page_up`, `copy_mode_page_down`                                            | `PgUp`, `Ctrl+F` `PgDown`                     |
| `copy_mode_bottom`                                                                    | `G`                                           |
| `copy_mode_screen_top`, `copy_mode_screen_middle`, `copy_mode_screen_bottom`          | `H`, `M`, `L`                                 |
| `copy_mode_paragraph_up`, `copy_mode_paragraph_down`                                  | `{`, `}`                                      |
| `copy_mode_matching_bracket`                                                          | `%`                                           |
| `copy_mode_repeat_char_search`, `copy_mode_repeat_char_search_back`                   | `;`, `,`                                      |

`0`, `^`, `$`, `w`, `b`, `Ctrl+B` and `gg` are fixed keys. They do what
`copy_mode_line_start`, `copy_mode_first_nonblank`, `copy_mode_line_end`,
`copy_mode_word_forward`, `copy_mode_word_backward`, `copy_mode_page_up` and
the top of the scrollback do, and you cannot rebind them.

### Line start and line end

`Home` moves the copy cursor to column zero of the line, as `0` does. `End`
moves it to the last nonblank character of the line, as `$` does, and not to
the blank cells up to the pane edge. `copy_mode_first_nonblank` moves it to the
first nonblank character, as `^` does, and has no default key. On a blank line
all three go to column zero. The keys also move the end of a `v` or `V`
selection.

| Action                     | Default key |
| -------------------------- | ----------- |
| `copy_mode_line_start`     | `Home`      |
| `copy_mode_first_nonblank` | none        |
| `copy_mode_line_end`       | `End`       |
| `copy_mode_exit`           | `Enter`     |

The keys are in the `copy_mode` section. They work only in copy mode. In the
search prompt, they do not move the cursor. `0`, `^` and `$` are fixed keys,
and you cannot rebind them.

Do not bind a key here that copy mode already uses, such as `y` or `v`, or a
key of a `[[keybindings.copy_pipe]]` entry. `tuios keybinds doctor` and the
config check warn about such a key. A copy pipe key runs the pipe, and the
binding does not run. A key that copy mode uses loses its copy mode action.

`copy_mode_exit` leaves copy mode, as `q` does, and gives the pane the
keyboard back. From a `v`, `V` or `Ctrl+V` selection it copies the selection
first, as `y` does, then leaves, as tmux does with `Enter`. In multi-pane copy
mode it copies every selection, as `y` does there.
In the search prompt `Enter` still runs the search. For the old behaviour,
where `Enter` does nothing in copy mode, set it to no key:

```toml
[keybindings.copy_mode]
copy_mode_exit = []
```

`Ctrl+A` and `Ctrl+E` are not defaults. `Ctrl+A` is a common leader key, and
`Ctrl+E` scrolls one line in tmux copy mode. To use them, add them to the
section:

```toml
[keybindings.copy_mode]
copy_mode_line_start = ["home", "ctrl+a"]
copy_mode_line_end = ["end", "ctrl+e"]
```

tuios cannot put two actions on one key. `tuios send-keys` cannot do it either,
because a key from `send-keys` does not go to copy mode.

### Word movement

`Shift+Left` and `Shift+Right` move by word as `b` and `w` do, including
counts and visual selections.

| Action                    | Default key   |
| ------------------------- | ------------- |
| `copy_mode_word_backward` | `Shift+Left`  |
| `copy_mode_word_forward`  | `Shift+Right` |

Rebind or disable them in copy mode:

```toml
[keybindings.copy_mode]
copy_mode_word_backward = []
copy_mode_word_forward = ["alt+right"]
```

The fixed `b` and `w` keys remain available. Terminal emulators must send
shifted arrow keys to tuios for the defaults to work.

### Hints in copy mode

`s` in copy mode puts hint labels on the text in view, so you can copy text
that you scrolled back to. See [docs/HINTS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HINTS.md#from-copy-mode).

| Key        | Where                    | Action  |
| ---------- | ------------------------ | ------- |
| `s`        | Copy mode                | `hints` |
| `Ctrl+B F` | Window and terminal mode | `hints` |

### Open the scrollback in the editor

`Ctrl+G` in copy mode opens the scrollback of the pane in your editor. The
file has all the scrollback and the screen, as plain text. zellij does the
same with `e`.

| Key        | Where     | Action            |
| ---------- | --------- | ----------------- |
| `Ctrl+G`   | Copy mode | `edit_scrollback` |
| `Ctrl+B E` | Any mode  | `edit_scrollback` |

The command palette entry is "Edit the scrollback in the editor".

- tuios uses the File editor setting first. Then it uses `$EDITOR`, then
  `$VISUAL`, then `vi`.
- vi, vim, nvim, nano, emacs, kakoune and helix open at the line of the copy
  cursor. Outside copy mode, they open at the top of the screen. Other
  editors open at the start of the file.
- In a session with a daemon, the text comes from the daemon. It has the
  full scrollback, also when your client has only part of it.
- The editor uses the terminal that tuios runs in. tuios comes back when the
  editor exits.
- The file is in a private folder. tuios removes the file when the editor
  exits, and when the client stops.
- A browser client or an SSH client from another machine cannot open the
  editor. tuios shows a message.

In copy mode, `e` and `E` move to the end of a word, as in vim. For this
reason, the editor key is `Ctrl+G`. `Ctrl+G` also opens a reply in the editor.
To use another key, set it in the `copy_mode` section:

```toml
[keybindings.copy_mode]
edit_scrollback = ["ctrl+o"]
```

The tmux preset uses `Ctrl+B E` to make the splits equal. With that preset,
the editor key is `Ctrl+B Ctrl+T E`.

### Other end of a selection

In a `v` or `V` selection, `o` moves the copy cursor to the other end of the
selection. The selected text does not change. The next motion moves the end
that the cursor is on now. Press `o` again to go back. If the other end is
outside the pane, the pane scrolls to show it. tmux and vim use `o` the same
way.

### Clear the scrollback

The `clear_scrollback` action clears the scrollback of the focused pane. It
also removes the rows above the prompt, and the prompt row moves to the top of
the pane. Ghostty, iTerm2 and Terminal.app do the same on `Cmd+K`.

| Action             | Default key |
| ------------------ | ----------- |
| `clear_scrollback` | None        |

The command palette entry is "Clear the scrollback".

- tuios sends no key to the program, so the shell does not redraw.
- When the shell marks its prompt with OSC 133, tuios keeps all the lines of
  the prompt.
- In a session with a daemon, the daemon clears the pane. Each client of the
  session shows the clear. An attach later does not bring the old rows back.
- The key also works in copy mode. tuios leaves copy mode.
- tuios clears nothing while a full-screen program, such as vim or less, uses
  the pane. tuios shows a message.

`tuios clear-history` clears the scrollback from the command line, as tmux
`clear-history` does. It keeps the screen. With `--screen`, it does the same
as the key. See [CLI\_REFERENCE.md](https://tuios.dev/docs/cli-reference/remote-control-commands#tuios-clear-history).

The action has no default key, because the host terminal usually keeps `Cmd+K`
for itself. To use `Cmd+K`, bind `super+k` in the `global` section. A key in
the `global` section works in terminal mode and in window mode.

```toml
[keybindings.global]
clear_scrollback = ["super+k"]
```

Then tell the host terminal to send `Cmd+K` to tuios. In Ghostty, add this line
to the Ghostty config:

```
keybind = cmd+k=unbind
```

In iTerm2 and Terminal.app, `Cmd+K` is a menu item. Remove or change its
shortcut in the settings of the terminal. A terminal that does not send the
Super key cannot send `super+k`. Bind another key, such as `Ctrl+B K`:

```toml
[keybindings.prefix_mode]
clear_scrollback = ["K"]
```

### Pipe a yank through a command

A yank can go through a command before it goes to the clipboard. tmux calls
this `copy-command` and `copy-pipe`. tuios has two parts:

- `appearance.selection.copy_command` runs one command on every yank in copy
  mode.
- A `[[keybindings.copy_pipe]]` entry binds a key in copy mode to its own
  command.

```toml
[appearance.selection]
copy_command = "tmux-copy-it"

[[keybindings.copy_pipe]]
key = "p"
command = "tr '\n' ' '"
cancel = true
description = "flatten"
```

The command runs with `sh -c`. It gets the selection on stdin. The clipboard
gets what the command writes to stdout. When the selection does not end with
a new line, tuios removes one new line from the end of the output.

When the command stops with exit code 0 and writes nothing, tuios does not
change the clipboard or the paste buffers. The dock shows a message. Use this
for a command that sets the clipboard itself, such as `tmux-copy-it`, or that
sends the text to a socket or a file. tmux does the same: the write of the
command stays.

The clipboard gets the selection itself in these cases:

- The command stops with an exit code that is not 0. The dock shows the exit
  code and the first line of stderr.
- The command runs for more than 10 seconds. tuios stops the command and the
  processes that it started.

tuios waits until the command closes its stdout. `xclip` starts a process that
stays open after `xclip` stops, and keeps stdout open. tuios then waits 1
second more. To prevent the wait, send the stdout of `xclip` to `/dev/null`.
This example puts each yank in the X primary selection. The command writes
nothing, so the clipboard does not change:

```toml
[appearance.selection]
copy_command = "xclip -selection primary >/dev/null"
```

The fields of a `[[keybindings.copy_pipe]]` entry:

- `key` is the key in copy mode. Write it as in the other sections.
- `command` gets the selection on stdin.
- `cancel` says what happens after the yank. With `false`, the default, copy
  mode stays on and the cursor stays where it is. tuios clears the selection.
  This is tmux `copy-pipe`. With `true`, copy mode stops, as with `q`. This is tmux
  `copy-pipe-and-cancel`.
- `description` names the entry in the dock messages. It is optional.

The entry takes its key from copy mode. An entry on `y` replaces the plain
yank. Copy mode does not use `p` or `P`. When an entry takes `q`, `Esc`, `Ctrl+C`, `v`, `V`, `/`,
`?` or a digit, tuios shows a warning when it loads the config. When no text is selected, the key
shows a message and runs nothing. While you type a search, the key goes into
the search.

Without `copy_command`, `y` copies the selection as it is. With
`copy_command`, `y` and `c` pipe the selection through that command. A
`[[keybindings.copy_pipe]]` key always uses its own command. A mouse
selection that copies on release does not use `copy_command`. A drag does not
run a command.

In multi copy mode, the command gets the text that `y` copies: the selection
of each pane, joined in the current format. It runs one time for all panes.
Use the `json` format to process each pane separately, for example with `jq`.
With `cancel = true`, multi copy mode stops in every pane.

The command runs on the machine that runs the tuios client. That is the same
machine as for a `shell` command key. For the SSH and web clients, it is the
server. The command starts in the folder of the focused pane and gets the
variables of a command key: `TUIOS_SESSION`, `TUIOS_SOCKET`,
`TUIOS_ACTIVE_PANE_ID` and `TUIOS_ACTIVE_PANE_CWD`. You can use tuios while
the command runs.

### Paste buffers

tuios keeps your recent yanks as paste buffers, as tmux does. A yank in copy
mode adds a buffer, and so does a mouse selection that you copy. The yank also
goes to the clipboard, as before.

| Key        | Action          | What it does                                  |
| ---------- | --------------- | --------------------------------------------- |
| `Ctrl+B ]` | `paste_buffer`  | Paste the newest buffer into the focused pane |
| `Ctrl+B #` | `choose_buffer` | Show the buffers, newest first, to choose one |

`Ctrl+B ]` takes the newest of your own buffers: what you copied, or set
yourself. A buffer that a program in a pane without `admin` set is never your
newest, so no such program can set what the key pastes. The paste goes to the pane that was focused when you pressed
the key, also when the focus moves before the text arrives. Each line feed
becomes a carriage return, as in tmux.

In the list, `Enter` or a click pastes the buffer, `d` deletes it, and `Esc`
or `q` closes the list. The list shows "from pane" and the pane's name on a
buffer that a program in a pane set, because you did not copy that text. A paste goes
in the bracketed paste marks when the program in the pane asks for them, as a
clipboard paste does.

tmux shows the list on `=`. In tuios, `Ctrl+B =` makes the splits equal, so
the list is on `#`, the tmux key for `list-buffers`. To use the tmux keys, move
the splits key and give `=` to the list:

```toml
[keybindings.prefix_mode]
equalize_splits = ["E"]
choose_buffer = ["="]
```

The daemon keeps the buffers, so every client and every session shares them.
A client with no daemon keeps its own. The buffers are in memory only, and
they go when the daemon stops. `[paste_buffers]` in `config.toml` sets how
many to keep. The commands `tuios list-buffers`, `show-buffer`, `set-buffer`,
`delete-buffer` and `paste-buffer` read and change the same buffers, and so
does `tmux` under the tmux shim.

## Copies between machines

`Ctrl+B u` opens the Copies panel. It shows one row for each copy between
machines, the newest first. The dock item `transfers` opens it too, with a
click. The command palette row is "Copies between machines".

| Key                 | Action                          | What it does                                  |
| ------------------- | ------------------------------- | --------------------------------------------- |
| `j` `k` `Down` `Up` | `transfers_down` `transfers_up` | Move the cursor                               |
| `p`                 | `transfers_pause`               | Pause the copy, or go on with it              |
| `x`                 | `transfers_cancel`              | Cancel the copy. tuios asks first             |
| `r`                 | `transfers_retry`               | Try a failed copy again from where it stopped |
| `c`                 | `transfers_clear`               | Remove the copies that ended                  |
| `Enter`             | `transfers_answer`              | Answer a copy that waits for an answer        |
| `Esc` `q`           | `transfers_close`               | Close the panel                               |

The keys are in `[keybindings.transfers]`. The panel key is
`prefix_transfers` in `[keybindings.prefix_mode]`.

A copy waits for an answer when a file is there on the other machine and the
copy was started with `conflict = "ask"`. The dock says `1 copy asks`. Press
`Enter` on the row to choose Replace, Keep both or Skip. Press `Space` to use
the answer for the other files of the copy. tuios does not open this question
by itself, because `tuios cp` in a pane asks the same question there.

When you drop files on a pane whose program runs on another machine, the
terminal pastes their paths. tuios asks whether to send the files to that
machine. Send copies them to a private drop folder there. When the copy is
checked, tuios pastes the path on that machine. Paste the text pastes the paths
as they are. A paste into a pane on this machine is not changed.

## Screenshots over a panel

`Ctrl+B C` opens capture mode over any panel or overlay too: the agents view, the
review, the palette, settings, a menu or a dialog. The panel stays open and is
part of the capture. The panes are under it, so capture mode does not offer
one: `enter`, `f` or a click takes the whole screen, and a drag takes a region
of it.

While a panel is open, the leader is held for one key. If that key is not the
screenshot key, the panel gets the leader and then the key, in that order, as
it did before. Copy mode and the scrollback browser keep the leader at once,
because both page up on `ctrl+b`.

## Settings

`,` in window-management mode, or `ctrl+b ,`, opens the settings page. It
reopens on the tab, row and search it was left on.

| Keys                                   | What it does                                      |
| -------------------------------------- | ------------------------------------------------- |
| `left`, `right`, `h`, `l`              | Change the row's value                            |
| `enter`, `space`                       | Toggle, cycle, or open the row's picker or editor |
| `tab`, `shift+tab`, `[`, `]`           | Next or previous tab, wrapping                    |
| `1` to `9`                             | Go to that tab                                    |
| `/`, or a letter the page does not use | Search every tab                                  |
| `backspace`, `delete`                  | Reset the row to its default                      |
| `ctrl+z`                               | Undo the last change made on the page             |
| `esc`, `q`                             | Close                                             |

A row changed from its default carries a dot after its name, and its
description says what the default is.

The search ranks every row of every tab by its name, its config key, its value
and its description, with the letters that matched lit, and each result names
its tab. In the search, `up` and `down` move through the results, `left`,
`right` and `enter` act on the row where it is, `tab` goes to the row on its
own tab, `delete` resets it, and `esc` clears the search and puts the page back
where it was; a second `esc` closes it. The command palette reaches the same
rows by name (`settings: pane background`), and `tuios list-options --search`
runs the same search from a shell.
