# Panes, panels and workspaces

URL: https://tuios.dev/docs/keybindings/panes-panels-and-workspaces

> Panes, panels and workspaces: 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.

## Editing sidebar files

Focus the sidebar with `s` in window mode or `Ctrl+B e`, or walk into it with
the terminal-mode focus keys from the outermost window (see Moving focus), then
select a file.
With both sidebar edges visible, `e` while the sidebar has keyboard focus
switches focus to the other edge; press it again to return. `Ctrl+B H` toggles
the independently configured opposite rail without changing the original
rail (`Ctrl+B b` still toggles that original rail). `Ctrl+B b` shows or
hides the rail in every session. Set `appearance.sidebar.per_session = true`
to keep a shown or hidden rail per session, as before. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/dock-and-rail#show-or-hide-the-rail-in-every-session).

`Enter` opens a folder or copies the path of a file. `Shift+Enter` opens a text
file in a new pane. The pane runs the editor set under Settings, Sidebar, File
editor. A folder keeps its navigation action. tuios does not edit a file that is
not text. The binding is `file_edit` in `[keybindings.sidebar_files]`.

`Y` copies the absolute path of the selected file or folder. The context menu
of a folder has a Copy path row that does the same. The binding is
`file_copy_path` in `[keybindings.sidebar_files]`.

`o` opens the selected file or folder with the system opener. On Linux this is
`xdg-open`. On macOS it is `open`. Under WSL it is `wslview`, and on Windows
it is the program for the file type. A `[[files.open]]` rule can name another
program for a pattern. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/files-input-and-focus#open-files-from-the-sidebar). The context
menu of a row has an Open with system row that does the same. The binding is
`file_open_system` in `[keybindings.sidebar_files]`. On a row that is not a
file, `o` keeps its sidebar action, which sorts the agents.

For a listing of another machine, `o` offers to open a copy here. Click the
message, or press the prefix and then `j`, to copy the file or folder to this
machine and open the copy. Press `esc` to say not now. The copy shows in the
Copies panel. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/files-input-and-focus#open-a-file-of-another-machine). A remote
client (`tuios ssh`, `tuios-web`) does not open the file. Press `Space` to
preview it, or `S` to send it here.

`I` pastes the path of the selected file or folder into the focused pane. The
context menu of a row has a Paste path in pane row that does the same. The
binding is `file_insert_path` in `[keybindings.sidebar_files]`.

### Drag a file into a pane

You can also drag a row with the mouse. Press a row, move the pointer, and
release the button over a pane. The pane gets the path. A press becomes a
drag when the pointer moves more than the drag threshold
(`mouse.drag_threshold`, 5 cells by default).

- While you drag, the row in the sidebar looks picked up.
- A heavy frame in the accent colour shows the pane under the pointer. A pane
  that does not take the path gets the frame in the warning colour.
- A label at the pointer shows the name, the pane and the program in the pane.
- `Esc` cancels the drag.
- A release over the sidebar, the dock or an empty area does nothing.
- A drag never opens quick look and never copies, also when you release it
  over the sidebar.
- A click on a file opens it in quick look. A click on a folder opens the
  folder.
- `Ctrl`+click or `Shift`+click on a row copies its path.

After the drop, the pane has the focus and the mode does not change.

tuios quotes the path for the program in the pane. It knows sh, bash, rbash,
zsh, dash, ksh, ksh93, mksh, lksh, oksh, loksh, pdksh, posh, yash, ash, hush,
fish, nu, csh, PowerShell, elvish and cmd. Other programs get POSIX single
quotes, except a name with a backslash before a quote or another backslash, or
ending in a backslash, which gets its quotes and backslashes written outside
the single quotes, so fish behind tmux or script reads it as a POSIX shell
does. A folder path ends in `/`. A space follows the path, so you can
type the next word. Hold `Alt` when you release a folder to type a cd to it.
The path goes in as a paste. A program that turned on bracketed paste gets it
as one paste.

tuios does not paste the path in these cases. The label and a dock note say
why.

- The pane is on another machine.
- The pane runs ssh or mosh, or its shell reports a folder on another machine.
- The file is in a listing from another machine.
- The name holds a line break or a control character.
- The pane is in copy mode.

A drag never copies or moves the file. To turn the drag off, set
`appearance.sidebar.file_drag = false`.

When the session runs on another machine, tuios does not check the file on your
machine. If the editor is not on that machine, no pane opens. tuios shows a
dock note that names the editor and the machine, so you know what to check.

With the File editor setting empty, a remote session uses `$EDITOR` from this
machine. Set the File editor if the far machine has a different editor.

tuios can not edit a file that lists from a different machine than the one the
session runs on.

`Shift+Enter` needs a terminal that reports modified Enter, such as one that
uses the Kitty keyboard protocol. On other terminals, use the Edit row in the
context menu of a file, or bind `file_edit` to a different key.

`S` sends the selected file or folder to a host. tuios asks which host, then
which folder. The folder field starts as `~/Downloads/tuios/`.
tuios makes the folder when it is not there. A file that is there stays, and
the copy gets the name `name (from HOST).ext`. The context menu of a row has a
Send to host row that does the same. The binding is `file_send` in
`[keybindings.sidebar_files]`.

`Space` shows a quick look preview of the selected row. The preview opens over
the panes and shows:

- code with syntax colours and line numbers,
- Markdown as formatted text,
- a picture, a page of a PDF or a film frame,
- the names in a folder.

A file that is not text shows its type and size. A long text opens at once, and
tuios reads more of it as you move. Line numbers after a jump to the end are
estimates, and the preview says so. A search or a count stops after 5 seconds
and says how far it went. Press `n` to go on.

A PDF shows one page and a bar with the page number. Click the bar to go to a
page. At 16 colours the preview shows the words of the page.

A film shows one frame and a bar with the time. Click or drag the bar to move to a
time. There is no playback. Press `t` to show 7 small frames from across the film.
At 16 colours the preview shows the facts of the film.

Markdown shows HTML as formatted text, with alerts, footnotes and reference links.
An image alone on its line shows as a picture when the terminal can draw one. A
table keeps every cell: a long cell wraps in its column. A table with too many
columns shows each row as a list of names and values. A `<picture>` shows the
source for a dark or a light theme, as the theme is. Quick look reads no address
on the web: an image there, a WebP, an SVG and an AVIF show as one line of their words.
A `<details>` block starts closed, and `Enter` inside the file opens it. A Mermaid
block shows as a diagram in text.

JSON is laid out for reading. CSV and TSV show as a table. An archive shows the
files in it. A binary file shows its first 16 KiB in hex. `J` and `K` step through
the frames of a GIF.

`Up` and `Down` (or `j` and `k`) move the cursor to the next row, and the preview
shows that row. `Space` or `Esc` closes the preview. A click outside it closes
it too. When the sidebar loses keyboard focus, the preview closes.

The mouse over the preview stays in the preview. A pane under it does not get
the focus or the mouse. Drag over the text or the Markdown to select it. A
double click selects a word, and a triple click selects a line. The selection
goes to the clipboard when you release the button. The next click or key
removes the selection.

These keys move inside the file. The preview shows the keys that work now. All
other keys go to the sidebar.

| Key                          | Action                                                           |
| ---------------------------- | ---------------------------------------------------------------- |
| `J` `K`                      | Move half a page, one page of a PDF, or 5 percent of a film      |
| `Ctrl+D` `Ctrl+U`            | Move half a page                                                 |
| Mouse wheel over the preview | Move 3 lines, one page of a PDF, or 1 percent of a film          |
| `t`                          | Show the small frames of a film, or hide them                    |
| `v`                          | Show the next view: the diff of a changed file, then the details |
| `Tab`                        | Move the keyboard inside the file                                |
| `f`                          | Fill the area of the panes, or go back                           |

Inside the file, every key acts on the preview:

| Key            | Action                                                                            |
| -------------- | --------------------------------------------------------------------------------- |
| `j` `k`        | Move one line, one page of a PDF, or 1 second of a film                           |
| `h` `l`        | Move 1 second of a film, or one column of a table                                 |
| `v`            | Show the next view: the diff of a changed file, then the details                  |
| `t`            | Show the small frames of a film, or hide them                                     |
| `d` `u`        | Move half a page                                                                  |
| `g` `G`        | Go to the start or the end, or the first or last page                             |
| `/`            | Search in a text. Lower case ignores case                                         |
| `n` `N`        | Go to the next match, or the one before                                           |
| `:`            | Go to a line number, or a page of a PDF                                           |
| `w`            | Wrap long lines, or cut them                                                      |
| `[`            | Start copy mode on the text                                                       |
| `e`            | Open the file in your editor in a new pane, at the line at the top of the preview |
| `f`            | Fill the area of the panes, or go back                                            |
| `Esc` or `Tab` | Move the keyboard back to the list                                                |
| `Space`        | Close the preview                                                                 |

Change these keys in `[keybindings.quick_look]` and
`[keybindings.quick_look_inside]`.

`[` in a text file starts [copy mode](https://tuios.dev/docs/keybindings/copy-mode#copy-mode) on the text, with the cursor
on the first line in view. All copy mode keys work: move, select with `v`,
`V` or `Ctrl+V`, search with `/`, and copy with `y`. The mouse works as in a
pane's copy mode: a click moves the cursor, a drag selects and copies on
release, and the wheel scrolls. Long lines wrap while
copy mode is on. A selection across a wrapped line copies the line whole. `q`
or `Esc` goes back to the preview keys.

### Paths in a pane or the agents view

A file path in a pane's output or in the agents view works like a link: an
absolute path, one under `~/`, `./` or `../`, or a relative one with a slash
in it, with an optional `:line` or `:line:col`. A relative path is taken from
the pane's folder, or in the agents view from the agent's worktree or pane
folder. Only a path that names a file or folder that is there counts: the first
time the pointer stops on a path, tuios checks the disk, and the path is
underlined when the check finds it.

`Ctrl+click` on a path in a pane, a click on one in the agents view, and a
hint's `Ctrl` label open it in quick look, at its line. A folder shows its
listing. A `file://` link opens the same way. The keyboard is inside the file
at once: the keys above work, `e` opens your editor, and `Esc` closes the
preview.

A pane on another machine, a session reached through another host, or a pane
that runs `ssh` shows another machine's files, so tuios finds no paths there.
Under `tuios ssh` and `tuios-web` the files are on the machine the panes run
on, and quick look reads them there, as the sidebar's preview does.

For a listing on another machine, that machine reads the file and sends the
preview. Its host policy must allow `files`. The binding is `file_quick_look`
in `[keybindings.sidebar_files]`.

A picture uses Kitty graphics when the terminal supports them. Other terminals
get block characters. At 16 colours the preview names the picture and does not
draw it.

`Ctrl+B f` searches file names below the directory of the focused pane. It also
works while you type in a pane. `Ctrl+F` searches below the folder that the
sidebar shows, while the sidebar has focus.
Type a name or a relative path and press `Enter`. tuios shows the sidebar, opens
the folder of that file and selects the file. The search skips `.git`,
`node_modules`, `.venv` and `target`. It stops after about 2.5 seconds, and its
title says `partial` when tuios did not search the whole tree. You can rebind
the actions in the keybind manager (`Ctrl+B k`) or in `config.toml`, for
example:

```toml
[keybindings.prefix_mode]
prefix_file_search = ["f"]

[keybindings.sidebar]
file_search = ["ctrl+f"]
```

## Modifier spellings

A key in `config.toml` can spell a modifier in more than one way. tuios reads each spelling as the same key. `tuios send-keys`, herdr keys and a tape take the same spellings.

| Write                      | tuios reads it as | Where         |
| -------------------------- | ----------------- | ------------- |
| `opt+`, `option+`, `meta+` | `alt+`            | all platforms |
| `cmd+`, `command+`, `win+` | `super+`          | all platforms |
| `control+`, `ctl+`         | `ctrl+`           | all platforms |

`meta` is Alt, as it is to tmux, emacs and readline. A kitty keyboard Meta key is a different key, and no spelling names it.

The order of the modifiers does not matter, so `shift+ctrl+x` is `ctrl+shift+x`. This applies to `leader_key`, to every binding table, and to `tuios keybinds explain`, `free` and `unbind`. `tuios keybinds explain opt+f12` shows `opt+f12 (tuios reads it as alt+f12)`. `tuios keybinds doctor` lists each key that tuios cannot read.

In `[keybindings.terminal_mode]`, `middle` names a press of the middle mouse
button. It accepts `ctrl`, `alt` and `shift`, such as `ctrl+middle`. Other
tables do not accept it. A program that uses the mouse, such as vim with
`mouse=a`, lazygit or tmux, gets a plain middle press. A binding with a
modifier runs over such a program too. Other mouse gestures are fixed.

You can use one `config.toml` on macOS and on Linux. On Linux, `opt+1` is `alt+1`. `tuios keybinds doctor` lists these keys for information.

tuios ignores a key that it cannot read, such as `ctrl+nope`, and loads the rest of the file. The action gets its default key when it has no other key. If another action already has that default key, the action has no key. A leader that tuios cannot read changes to `ctrl+b`. tuios shows a config problem when it starts. The log viewer (leader `D` `l`) names each key and its file. `tuios keybinds doctor` shows the same information. A table name that tuios does not have, such as `[keybindings.terminal]`, is reported the same way, with the table you most likely meant.

A `super+` chord needs a terminal that sends the Super key. Most macOS terminals keep Command chords for their own menus. Ghostty and kitty send an unbound Command chord under the Kitty keyboard protocol.

## Moving focus

Four keys move focus to the window in a direction. Each key has a binding in window mode, in terminal mode, and after the prefix.

| Direction | Window mode | Terminal mode | After the prefix key |
| --------- | ----------- | ------------- | -------------------- |
| Left      | `h`         | `alt+left`    | `left`               |
| Down      | `j`         | `alt+down`    | `down`               |
| Up        | `k`         | `alt+up`      | `up`                 |
| Right     | `l`         | `alt+right`   | `right`              |

Focus goes to the nearest window that lies in that direction and faces the focused window. At the edge of a tiled layout, focus stays where it is. With tiling off, a window that does not face the focused window can also get focus.

Set `appearance.focus_wrap = true` to wrap focus at the edge of a tiled layout. Focus then goes to the window on the far side that faces the focused window. For example, left from the leftmost window goes to the rightmost window in the same rows. A window that fills the layout in that direction keeps focus. The option is off by default. See [CONFIGURATION.md](https://tuios.dev/docs/configuration/files-input-and-focus#wrap-focus-at-the-edge).

The terminal-mode and prefix keys go on into the sidebar. When no window lies in that direction and the sidebar is shown on that edge, the sidebar gets the keyboard, as `s` in window mode does. With `focus_wrap` on, focus wraps first. The sidebar gets the keyboard only when no window is on the far side. The key in the opposite direction gives the keyboard back to the window you came from. A hidden sidebar stays hidden.

With tiling off, `h` and `l` snap the focused window to the left or right half of the screen. `j` and `k` always move focus. The actions are `snap_left`, `snap_right`, `focus_down` and `focus_up` in `[keybindings.layout]`.

In the scrolling layout, left and right move between columns. Up and down move between the windows in one column. With `focus_wrap` on, up and down wrap inside the column. Left and right do not wrap.

## Finding a pane

### Pane labels

`Ctrl+B Q` puts a large label on each pane of the workspace. Type a label to
focus that pane. `esc` closes the labels. `backspace` takes back the last key.
`q` also closes, when `q` is not a label key. The action is `display_panes`,
as in tmux.

The labels are digits by default, in the order that `select_window_1` to
`select_window_9` count the panes. Thus label `3` is the pane that `3` selects
in window mode. A minimised pane gets no label. With more panes than keys, a
label has two keys. A key with `Shift` is the same key.

Set the keys in `[panes]`. Letters `a` to `z` and digits are allowed. The keys
that come first go to the first panes.

```toml
[panes]
label_keys = "asdfghjkl"
```

When a pane is zoomed, the zoomed pane shows its label. A list under it
shows the labels of the panes that the zoom hides. A label of a hidden pane
moves the zoom to that pane. A pane that is mostly off the screen, or too
small for its label, is in the same list.

The labels close when the layout changes: a pane opens, closes, moves or
zooms, or the workspace or the session changes. A click or the mouse wheel
also closes them. In multifocus, a label key goes to the labels and
not to the panes.

### The pane navigator

`Ctrl+B /` opens the pane navigator. It shows a tree of sessions, workspaces
and panes on the left, and a preview of the highlighted row on the right. The
sessions on the machines in `[hosts]` are in the tree too. The action is
`choose_tree`, as in tmux.

| Key              | What it does                                           |
| ---------------- | ------------------------------------------------------ |
| `j`, `k`, arrows | Move                                                   |
| `l`, `→`         | Open a session or a workspace                          |
| `h`, `←`         | Close it, or go to its parent row                      |
| `space`          | Open or close                                          |
| `enter`          | Go to the row: the session, the workspace and the pane |
| `/`              | Search                                                 |
| `v`              | Change the layout: tree, flat, cards                   |
| `esc`, `q`       | Close the navigator                                    |

The navigator has three boxes. Search is at the top and shows how many panes
match, as `3/7`. Panes is the list. Preview shows the screen of the pane under
the cursor, in the colors of that pane.

The list has three layouts. Tree shows the sessions, their workspaces and their
panes. Flat shows one row for each pane, with its session and workspace. Cards
shows two rows for each pane: the name and the command, then the session, the
workspace and the folder. `v` changes the layout. Your client keeps the last
layout until it closes. `[panes] navigator_layout` sets the first layout. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration).

A session name has the color of the session in the sidebar. A dot in front of
a pane shows the state of its agent. After the pane name is the command that
runs in the pane, or the shell when the pane is at its prompt. A pane that has
no name and no title shows its folder as its name. A search shows the matched characters in
the accent color.

Press `/` and type to search all panes. The search reads each pane's name,
title, folder, running command, session and workspace. It also reads the last
40 lines of each screen. A pane that matches only by its screen text shows the
matching line on its row. `esc` stops the search and keeps the results. A
second `esc` clears the search.

To open the navigator ready to type, so `Ctrl+B /` then a name finds a pane,
set this in `config.toml`. `esc` with nothing typed then closes it.

```toml
[panes]
navigator_search = true
```

The current session's panes are read from your client, and the preview of
those panes is live. The other sessions are read when the navigator opens.
Their preview shows the screen as it was then, with its colors. The preview
shows colors and text only. Links, clipboard writes and other control sequences
from a pane do not reach your terminal. A click on a pane goes to it. A
click on a session or a workspace opens or closes it.

`tuios list-windows --all --text 40 --json` prints the same rows for a script.
See [CLI\_REFERENCE.md](https://tuios.dev/docs/cli-reference/inspection-commands#tuios-list-windows).

### New task

`Ctrl+B +` opens the task capture sheet from any mode. Write the task: the
first line is the card's title, and the rest, with any image you paste (its
path, or `ctrl+v`), is its prompt. The card goes to the current session.
Under it, `Project` is the repository of the focused pane's folder, by its
origin URL, so the card shows on that repository's board in every session and
on linked machines; the arrows turn it to `None, this session` for a card of
the session only. `Stage` is Todo or Plan first, and `Agent to start` is the
agent `ctrl+enter` starts. With a linked machine, `Machine` says where that
agent starts: `This machine` (the default), `Any machine` (the machine with
the most room, as [Any machine](https://tuios.dev/docs/cli-reference/daemon-mode#any-machine) picks it), or
one linked machine. On another machine the agent's pane holds the card here
over that machine's link back. `tab` steps through them and the
arrows change one.
`enter` adds the card and closes. `ctrl+enter` adds it and starts the agent on
it, which holds the card from the start; with Plan first it starts in the
agent's own plan mode where it has one. `esc` closes and keeps the draft for
the next open. The action is `prefix_new_task`, and the command palette has it
as "New task".

### Go to anything

`Ctrl+B G` opens the go-to picker. It lists every place you can go in one list: agents, sessions, the workspaces of each session, and panes. The action is `goto_picker`. The command palette has it as "Go to: an agent, session, workspace or pane".

Each row starts with its kind, then says where the place is:

```
agent      claude · payments › 1 › api    needs you: approve Bash ●
session    payments [space: surge]                          3 panes
workspace  payments › 2 · api-tests                          1 pane
pane       payments › 1 › nvim                ~/src/payments
```

A pane of the session you are attached to ends with its working directory, with your home folder as `~`. On a narrow screen the folder is cut in the middle, and it is left out before the name gives way. `current` stays last.

With nothing typed, the first row is the place you were on last, so `Ctrl+B G` and `enter` take you back to where you were. The agents that need you come right after it, the one waiting longest first, then the other places you were on recently, the most recent first, then every agent, session and workspace. Panes are listed once you type something. A session has many panes, and the ones you were just on are already in the recent places.

Typed words are a fuzzy search over the names a row shows: the session, the workspace, the pane and its folder, and for an agent its harness and its last message. A `key:value` term narrows the rows instead, and every term has to match. The terms are the selector the agents view takes (`harness:`, `state:`, `needs:you`, `session:`, `group:`, `host:`, `name:`), and three more:

| Term                                                                       | Keeps                                                             |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `kind:agent`, `kind:session`, `kind:workspace` (or `kind:ws`), `kind:pane` | Rows of that kind                                                 |
| `space:NAME`                                                               | Rows of the sessions filed under that space                       |
| `ws:N`                                                                     | Agents, workspaces and panes on that workspace, by number or name |

A value is a glob, and commas between values mean any of them, as in `kind:session,workspace`. A term that does not fit a row leaves it out: `harness:` keeps only agents, and `ws:` leaves out the sessions. `@`, `#` or `!` at the start of the query is `kind:agent`, `kind:session` or `kind:workspace`. For example, `#space:surge` lists the sessions in the surge space, and `@needs:you` lists the agents that need you.

| Key                 | What it does                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| The list keys       | Move. See [Lists and panels](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#lists-and-panels) |
| `enter`             | Go there: the session, then the workspace, then the pane                                                      |
| `@`, `#`, `!` first | Filter to agents, sessions or workspaces. The picker's hint shows them as `@ # ! filter`                      |
| `ctrl+u`            | Clear the query                                                                                               |
| `esc`               | Close the picker                                                                                              |
| `ctrl+r`            | Rename the session or workspace on the row. The picker stays open under the rename                            |
| `ctrl+d`            | Delete the session on the row, after a `y`. Never the session you are on                                      |

The keys that opened the old lists open this picker with the filter typed: `Ctrl+B S` on `# ` (the sessions), `Ctrl+B W` on `! session:NAME` (this session's workspaces), and the palette's "All windows" on `kind:pane session:NAME` (this session's panes). With `# NAME` typed and no session called NAME, `enter` makes that session.

Workspaces and panes are listed for the sessions on the machine you are attached to. A session on another machine is listed, and its agents are, and `enter` on it attaches that machine as the rail does. A workspace of a session you are not attached to shows its number, because its name is not sent to your client.

## Neovim pane navigation

The optional [tuios-nvim-navigator](https://github.com/Tim4c/tuios-nvim-navigator)
plugin lets the terminal-mode focus keys move through Neovim splits first. The
feature is off by default. Set `appearance.nvim_navigation = true` to enable
it. At a split edge, TUIOS moves to the adjacent pane instead, or into the
sidebar when the pane is the outermost one on that side. With
`appearance.focus_wrap = true`, TUIOS wraps to the pane on the far side first. The plugin
announces when it is active, so the same keys keep their normal TUIOS behaviour
in shells and other programs.

By default, both projects use `alt+left`, `alt+down`, `alt+up` and
`alt+right`. If either side is customized, its four mappings must match the
`terminal_focus_left`, `focus_down`, `focus_up` and
`terminal_focus_right` bindings in TUIOS.

The plugin uses the private OSC 7777 messages below. They are consumed by
TUIOS and never shown in pane output:

```text
OSC 7777 ; tuios-nvim-navigator ; state ; active BEL
OSC 7777 ; tuios-nvim-navigator ; state ; inactive BEL
OSC 7777 ; tuios-nvim-navigator ; focus ; <direction> BEL
```

`<direction>` is `left`, `down`, `up` or `right`. A custom Neovim integration
may emit the same messages. TUIOS accepts focus requests only from the focused
pane in terminal mode, and only immediately after it forwarded the matching
focus key to that pane. Window-management mode always keeps the focus keys for
TUIOS itself.

## Lists and panels

Every list in the TUI moves the same way: the command palette, the launcher,
the settings page, the agents view, the mailbox, the keybind manager, the theme
editor, the theme, glyph and effect pickers, the layout and machine pickers,
go-to (which also lists the sessions, workspaces and panes), the navigator, the
window picker, the quit and context menus, the dock and rail editors and the
tape manager.

| Keys                                        | What it does                                                                                                                                  |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `up`, `down`, `ctrl+p`, `ctrl+n`            | Move one row. Up on the first row goes to the last, and down on the last to the first                                                         |
| `home`, `end`                               | The first or last row                                                                                                                         |
| `pgup`, `pgdown`                            | A page up or down, stopping at the ends                                                                                                       |
| `k`, `j`, `g`, `G`                          | Up, down, first and last, in a list with no filter to type into                                                                               |
| `ctrl+u`                                    | Clear a typed filter (fixed)                                                                                                                  |
| `alt+backspace`, `ctrl+w`, `ctrl+backspace` | Delete the word before the caret in a typed filter (fixed). `alt+backspace` is `Option+Backspace` on a Mac whose terminal sends Option as Alt |
| wheel                                       | Scroll the list under the pointer, stopping at the ends (fixed)                                                                               |

The theme editor and the keybind manager keep a cursor for each of their
tabs. Go to another tab and back, and the cursor is on the row you left. A
filter that changes puts its list back on the first row.

A footer names the move keys as `[keybindings.lists]` binds them: `↑↓` while
the arrows come first (`up/down` with ASCII glyphs), and otherwise the first up
and the first down key, such as `ctrl+k/ctrl+j`. A motion with no key leaves
its hint out.

The word keys take a word the way the shell's `Option+Backspace` does: they skip
the characters at the end that are not part of a word, then take the word. A word
is letters, digits and `_`, and a blank, `/`, `.` or `-` ends one. So
`src/dir1/dir2` becomes `src/dir1/`, then `src/`, then nothing. Every short text
field in tuios takes them, the rename, file and new worktree dialogs among them.

Every short text field also has a caret. `left` and `right` move it a
character; `alt+left`, `ctrl+left` and `alt+b`, and `alt+right`, `ctrl+right`
and `alt+f`, a word; `home` and `ctrl+a`, and `end` and `ctrl+e`, to the start
and the end. `alt+d`, `alt+delete` and `ctrl+delete` delete the word after the
caret, `ctrl+k` cuts from the caret to the end, `ctrl+u` clears the field, and
typed or pasted text goes in at the caret. In a list's filter, and in the help
and settings searches, `left` and `right` keep their own meaning (the section,
the tab or the row's value), and `home` and `end` move the list, so there the
caret moves with the other keys.

The agents view's one-line fields (the selector line, the reason for a reject
and the answer to a prompt) take these keys too, and have more: `ctrl+z`
undoes, `shift` with a move key selects, and a long line wraps in place of
scrolling sideways.

The movement keys are the `[keybindings.lists]` section. Every list in tuios
moves on them: the pickers and dialogs, the review panel, the scrollback
browser's command list, the composer's paste pager, the spawn sheet, and the
explorers behind `tuios keybinds browse`, `tuios config browse` and
`tuios help -i`. The agents view's compare answers with `J` (judge) and `K`
(keep), moves between attempts with left and right, and scrolls with `j` and
`k`; only its page keys come from this section. Each action takes the keys that do it:

| Action           | Default keys          |
| ---------------- | --------------------- |
| `list_up`        | `up`, `ctrl+p`, `k`   |
| `list_down`      | `down`, `ctrl+n`, `j` |
| `list_page_up`   | `pgup`                |
| `list_page_down` | `pgdown`              |
| `list_first`     | `home`, `g`           |
| `list_last`      | `end`, `G`            |

A key that is a single printable character is a letter key. Only a list with no
filter to type into reads it, because a list with a filter keeps its letters
for the filter. To move on `ctrl+j` and `ctrl+k` as well as the arrows:

```toml
[keybindings.lists]
list_down = ["down", "ctrl+j"]
list_up   = ["up", "ctrl+k"]
```

An action you name replaces its default keys, so the example above gives
`ctrl+n`, `ctrl+p`, `j` and `k` back to the pane or the filter. An action you
leave out keeps its defaults, and `list_page_down = []` unbinds it.

Set `appearance.wrap_lists = false` to stop at the ends instead of wrapping.
The close-session and file confirmations never wrap, so up from Cancel cannot
land on the answer that deletes.

With nothing typed, the command palette lists its commands under category
headers. The headers are not rows: the cursor steps over them. Once you type,
the commands are ranked by how well they match, and each row names its
category in a quiet column on the right.

Type `#` to search actions instead of commands. `#close` lists every action
with "close" in its name, key or description, with the keys it is on today.
Press `Enter` to run the action. The palette closes first, so the action works
on the pane and the mode underneath, as its key would. Press `ctrl+e` to open
the keybind manager on the action, to rebind or unbind it. The footer shows
that key while a `#` search is open.

Some actions work only in their own view, such as a rail, Inbox, mail or copy
mode key. The palette has nothing for them to act on, so `Enter` on one opens
the keybind manager, as `ctrl+e` does.

The prefix menu (which-key) shows the keys after the leader in sections
(Windows, Panes, Sessions, Modes, Menus, Tools, and Agents once an agent has
run), laid out in as many columns as the screen holds. A key marked with `+`
opens a further menu. On a screen too narrow for every column, the
descriptions are cut before any key is left out.

The key hints at the foot of a panel stay on one row. When they do not fit,
they shorten in steps. First, `ctrl+` becomes `^`, `alt+` becomes `M-` and
`shift+` becomes `S-`. Then the least important hints go, one whole hint at a
time. The way out, such as `esc`, stays. Only when the most important hints
still do not fit do their labels go, from the last hint back. A hint is never
cut in the middle of a word.

### The rename dialog

One dialog renames a window, a session and a workspace. It opens holding the current name. Its keys are fixed.

| Keys                                        | What it does                                        |
| ------------------------------------------- | --------------------------------------------------- |
| `enter`                                     | Save the name                                       |
| `esc`                                       | Cancel                                              |
| `ctrl+u`                                    | Clear the field                                     |
| `alt+backspace`, `ctrl+w`, `ctrl+backspace` | Delete the word before the caret                    |
| `ctrl+c`                                    | Clear the field, or cancel when it is already empty |

The field has a caret, and takes the caret and word keys every short field
takes (see [Lists and panels](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#lists-and-panels)): `home` and `end`, `alt+d`
and the others. A click on the `clear` hint in the dialog's border clears the
field too. In the help's search, `ctrl+u` clears the query.

### Mode keys in the dock

Copy mode, multi copy mode and hints mode show their keys at the right end of
the dock while the mode is open. The keys follow the rule for panel footers
above, so a narrow screen shows fewer keys and never part of one. The main
action and the way out of the mode always show. In hints mode, `?` shows all of
its keys in the help. A message that arrives while a mode is open shows in the
place of the keys until the message goes. The dock component for the keys is
`copy-help`.

An empty list says why it is empty in the middle of the panel, with the one key
worth pressing next under it. A list that is still loading draws nothing for
its first half second, so a fast load never flashes a "reading" line.

## Messages

A message shows at the right end of the dock. A message that is too long
for the dock stops after its last whole word, with `…` and `more`. A word with
no space in it, such as a long path, is cut where the room ends.

- Put the pointer on a message to hold it. It does not go away while the
  pointer is on it. A key press, or the terminal losing focus, ends the hold.
  The hold ends after 60 seconds.
- Put the pointer on a long message to see its first lines above the dock.
- Click a long message to read all of it in the message view. A click on a
  pane's request to set the clipboard allows it.
- Click a short message from a pane to go to that pane.

| Keys                                          | Where        | What it does                                                                                                            |
| --------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `ctrl+b N`                                    | anywhere     | Show the last message from a pane, or the last message that was too long for the dock, also after it went from the dock |
| `ctrl+b j`                                    | anywhere     | Go to the pane of the newest message. On an agent integration notice, ask to install the integration                    |
| `j`, `k`, `up`, `down`, wheel                 | message view | Scroll one line                                                                                                         |
| `ctrl+d`, `ctrl+u`, `space`, `pgdown`, `pgup` | message view | Scroll half a page                                                                                                      |
| `g`, `G`, `home`, `end`                       | message view | Go to the first or last line                                                                                            |
| `y`                                           | message view | Copy the message                                                                                                        |
| `enter`                                       | message view | Go to the pane the message came from                                                                                    |
| `esc`, `q`                                    | message view | Close the message view                                                                                                  |

The log viewer (`ctrl+b D l`) lists every message the dock showed, and every
warning and error. The entry under the cursor shows wrapped under the list.
Press `enter`, or click an entry, to read it in the message view. `E` copies
the errors and `A` copies the whole log.

## Hints

`Ctrl+B F` puts a short label on each URL, path, hash, address and number in
the focused pane. Type a label to copy the text. Type it with `Shift` to copy
the text and type it into the pane. Type it with `Ctrl` to open a URL or a
path. `?` shows all of the keys of hints mode. `esc` closes. The dock shows
the keys while the labels show. See [HINTS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HINTS.md) for the patterns and the
`[hints]` settings. The action is `hints`, so you can bind it to a different
key.

The `hints_all_panes` action puts labels on all panes that the workspace
shows. The focused pane gets the shortest labels. `Shift` and a label types
the text into the focused pane. This action has no default key. Bind it, or
run it from the command palette. Set `hints.all_panes = true` to make
`Ctrl+B F` do the same.

## Links

`Ctrl+click` on a link opens it. `Shift+click` also opens it, but most
terminals keep `Shift+click` for their own selection. Hover a link to see
where it goes. The label under the pointer shows the real target, also when
the text on the screen is different.

`Ctrl+click` and drag still moves the pane. A link opens only when the
pointer does not move. `appearance.link_click` sets which click opens a
link. See [CONFIGURATION.md](https://tuios.dev/docs/configuration/files-input-and-focus#opening-links) for the
settings, the opener and a table of terminals.

A pane can address another pane with a `tuios://window/<id>` link, where
`<id>` is the pane's short id from the sidebar or `list-windows`. A plain
`Ctrl+click` there jumps to that pane, and switches to its session first
when the pane is in another session of the same daemon. A
`tuios://window/<id>/close` link asks first: the confirmation names the
pane and only a second click closes it.

## Moving a pane with the mouse

Drag a tiled pane by its title bar, or `Ctrl+click` anywhere in it and drag. In BSP tiling, dropping it on the middle of another pane swaps the two, and dropping it near an edge of another pane splits that pane and puts the dragged pane in the half toward that edge. While the button is down, the place the pane will land is highlighted. See [LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md#moving-a-pane-with-the-mouse).

## Scratch terminal

`Ctrl+B g` shows the scratch terminal, a small layout of panes in a box over
the current layout. Press it again to hide the box. The shells keep running
between shows. Inside the box the window keys act on its panes: split, move
the focus, resize, swap, zoom and close. The key works from inside the box.
The action is `toggle_scratch`, and `[scratch]` sets the size of the box. See
[SESSIONS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#the-scratch-terminal). To add more scratch terminals
on keys of their own, see [Command keys](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#command-keys).

## New worktree

`Ctrl+B U` makes a worktree of the repository of the focused pane's folder.
A small dialog asks for the branch name. `tab` moves to the session name.
Leave the session name empty to use the name the dialog shows. `enter` makes a
new branch in a new worktree and a session in it. The session is grouped under
its repository in the sidebar, and tuios switches to it. This is what
`tuios worktree new` does. `esc` closes the dialog.

If the focused pane is not in a git repository, a message says so. The action
is `new_worktree`, and the command palette has it too. A right-click on a
session or a repository in the sidebar opens the same dialog.

## Session note

`Ctrl+B I` opens a one-line editor with the note of the session. A note says
what the session is for or what comes next. `enter` saves the note. An empty
note removes it. `esc` closes the editor. The action is `set_note`. The command
palette and the menu of a session row in the sidebar have it too.

The dock shows the note when you attach or switch to the session. See
[SESSIONS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#return-notes).

## Picture in picture

`p` in window mode pins the focused pane as the picture-in-picture view, a
small live copy of the pane in a corner of the screen. Press `p` again, on any
pane, to unpin it. A click on the view focuses the pane. The action is
`toggle_pip`, and `[pip]` sets the size and the corner. See
[SESSIONS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#picture-in-picture).

## Rail pane

`P` in window mode gives the keyboard to the pane in the rail's pane section.
`alt+esc` gives it back. The action is `focus_rail_pane`. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/dock-and-rail#the-rails-pane-section).

## Spotlight

`B` in window mode turns the spotlight on and off. The spotlight dims the
screen outside a circle around the pointer. `Ctrl+B B` turns it on and off in
any mode.

While the spotlight is on, the dock shows a Spotlight chip with the key that
turns it off:

| Where         | Turn off the spotlight               |
| ------------- | ------------------------------------ |
| Window mode   | `Esc`                                |
| Terminal mode | `Ctrl+B B`                           |
| Any mode      | Click the Spotlight chip in the dock |

In terminal mode `Esc` goes to the program in the pane, so vim and other
programs get it. An open dialog, menu or popup closes before `Esc` turns the
spotlight off. The actions are `toggle_spotlight` and
`toggle_spotlight`, and `[spotlight]` sets the size and the dimming.
The key was `b` in earlier versions.

## Pick a path

`Alt+;` in terminal mode opens the path picker at the cursor of the focused
pane. `Ctrl+B .` opens it too. The picker lists the folder that the shell in
the pane is in. Folders come first, then files. Type to filter the names.
Press `Enter` to type the path of the selected name at the cursor.
tuios quotes the path for the shell in the pane, by the same rules as a drag
from the sidebar. See [Drag a file into a pane](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#drag-a-file-into-a-pane).

| Key                                          | What it does                                           |
| -------------------------------------------- | ------------------------------------------------------ |
| Text                                         | Filter the names                                       |
| `Up`, `Down`, `Ctrl+P`, `Ctrl+N`             | Move the selection                                     |
| `Tab`                                        | Open the selected folder. On a file, complete the name |
| `Shift+Tab`, `Backspace` with no filter text | Go up one folder                                       |
| `/` at the start                             | Start an absolute path                                 |
| `~/` at the start                            | Start a path in the home folder                        |
| `Enter`                                      | Type the path and close the picker                     |
| `Alt+H`                                      | Show or hide the hidden files                          |
| `Esc`                                        | Close the picker and type nothing                      |

The filter line shows the path that you built, for example `src/app/`. A
click on a name types its path. The mouse wheel moves the selection.

The path is relative to the folder of the pane. A path that starts with `/`
or `~/` stays absolute. tuios puts a path with a space or a special character
in quotes. When the program in the pane turned on bracketed paste, tuios
sends the path as a paste. Else it types the path.

The picker works in a pane on another machine. The daemon on that machine
lists the folder, with the same read rules as the sidebar's files section.
When the shell in the pane runs ssh to another machine, the picker does not
open.

The action is `pick_path`. `path_picker.show_hidden = true` shows the hidden
files when the picker opens. The default is `false`.

## Calm mode

`Ctrl+B Z` turns calm mode on and off. Use it to keep your attention on one
task. While calm mode is on:

- Nothing moves. Window slides, panel fades, the working-agent shimmer and the
  copy sweep stop. Your `appearance.motion` level does not change.
- Nothing blinks. The cursor is steady.
- Messages from panes, agents and mail do not show in the dock. The log keeps
  them. An agent that needs you still shows its message, and so do warnings
  and errors.
- The dock tabs do not mark output on other workspaces. The bell mark stays.

The dock shows `calm` while it is on. `calm 3` means that 3 messages are in
the log. When you turn calm mode off, tuios tells you how many messages came
in. The action is `toggle_calm`. To keep calm mode on after a restart, set
`appearance.calm = true`. See [CONFIGURATION.md](https://tuios.dev/docs/configuration/motion-rendering-and-themes#calm-mode).

## Paste an image

`Ctrl+B V` pastes the image on your clipboard into the focused pane. tuios
saves the image to a file on the machine where the pane runs. Then it pastes
the path of that file into the pane. The pane can run on this machine or on a
host. Claude Code, Codex and other agents read an image from a path in the
prompt. The action is `paste_image`, and the command palette has it too.

The paste binding also pastes an image. `terminal_paste_host` in
`[keybindings.terminal_mode]` is bound to `Ctrl+Shift+V`, `Super+V`,
`Shift+Super+V` and the middle mouse button by default. The middle button
pastes from the clipboard, not from the primary selection. A program that uses
the mouse gets the middle button instead. `paste_clipboard` runs
the same operation outside terminal mode. When the clipboard holds an image
and no text, the paste binding pastes the image. When the clipboard holds text,
it pastes the text. Some terminals send an empty paste when the clipboard holds
only an image. tuios then pastes the image.

A browser can put a link or text beside a copied image. The paste key then
pastes the text. `Ctrl+B V` always pastes the image.

The paste key waits at most 0.3 seconds for the list of clipboard types. When
the clipboard tool is slower, or cannot list the clipboard, the paste key
pastes text. It then does not ask the tool again until tuios restarts.

`Ctrl+V` alone goes to the program in the pane. Claude Code reads the
clipboard on `Ctrl+V` itself, and that only works in a pane on this machine.
For a pane on a host, use `Ctrl+B V`.

tuios reads the image with the clipboard tool of your system:

| System         | Tool                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| Linux, Wayland | `wl-paste` from wl-clipboard                                                                                       |
| Linux, X11     | `xclip`. `xsel` cannot read an image.                                                                              |
| macOS          | `osascript`, or `pngpaste` when it is installed                                                                    |
| Windows        | PowerShell                                                                                                         |
| WSL            | `powershell.exe`, which reads the Windows clipboard. WSLg's `wl-paste` and `xclip` see no image copied on Windows. |

The file is a PNG, JPEG, GIF, WebP, BMP or TIFF image of 8 MB or less. Only
you can read it. tuios deletes it after one hour, or when the daemon stops.
The file is in the `paste` folder next to the tuios socket. The folder keeps
at most 50 images and 100 MB. When it is full, tuios deletes the oldest image.
If the `paste` folder is a symbolic link, tuios does not paste.

### A pane on another machine

A pane can run on another machine in three ways. In each, tuios writes the
image on that machine:

- A session on a host, attached with `tuios attach --host NAME`. The daemon on
  the host writes the file.
- A window on a host in a session of this machine. The daemon on the host
  writes the file.
- A pane of this machine that runs `ssh` or `mosh` to another machine, such
  as `ssh build` or `ssh -t build tmux`. tuios reads the ssh command line from
  the process. It resolves that line and each `[hosts]` entry with `ssh -G`.
  It compares the host name, the user, the port and the jump hosts. When
  exactly one entry is the same, tuios copies the image to the drop folder of
  that host and pastes the path there.

The other machine must allow `files` from this machine. If it does not, tuios
pastes nothing and shows the line to add to the config on that machine.

tuios pastes nothing in an ssh pane in these cases. A message says why.

- No `[hosts]` entry is the machine of the ssh command. Add the machine with
  `tuios hosts add NAME ADDR`.
- More than one `[hosts]` entry is that machine. Keep one of them.
- tuios cannot read the ssh command line, for example because it has `-F` or
  `-o ProxyCommand`.
- The shell over there reports a folder on another `[hosts]` machine: the pane
  runs ssh inside ssh. Paste the image in a pane on that machine.

An ssh tunnel (`ssh -N`, or `-f`, `-n` or `-W` without `-t`) does not read
what you type. tuios saves the image on this machine for it. So does a pane
that only reports a folder on another machine and runs no ssh.

tuios does not read the clipboard in these cases:

- The client runs in a browser. Save the image to a file and paste the path.
- The client runs on another machine through `tuios ssh`.
- The client runs inside ssh. The clipboard there is the other machine's.
  An X display that `ssh -X` forwards is the exception: tuios reads it.
- The paste comes from `send-keys`.

## Command keys

A `[[keybindings.command]]` entry binds a key to a command that you write.

```toml
[[keybindings.command]]
key = "prefix+alt+g"
type = "scratch"
command = "lazygit"
description = "Lazygit"
width = "80%"
height = "80%"
```

- `key` is the key that runs the command. A key that starts with `prefix+`
  works after the leader (`Ctrl+B`). Any other key works in window mode and
  in terminal mode.
- `type` is one of these:
  - `scratch`: a scratch terminal of its own. The key shows it and hides it,
    as `Ctrl+B g` does for the built-in one. Each entry has its own layout:
    you can split it. One scratch terminal is on the screen at a time. When
    the command exits, its pane closes. When no pane is left, the next press
    starts the command again. With no `command`, the first pane runs your
    shell.
  - `popup`: a popup that closes when the command exits. This is the default.
  - `pane`: a new pane in the layout, next to the focused pane. It closes when
    the command exits.
  - `shell`: the command runs with no window. You do not see its output. When
    the command fails, the dock shows a message.
  - `plugin_action`: the command is the id of a herdr plugin action, for
    example `example.layout.apply`. The daemon runs the action. The plugin
    must be enabled. When no plugin has the action, tuios shows a config
    problem. This works only in a daemon session on this machine. See
    [plugins](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/PLUGINS.md).
- `command` runs with `sh -c`, so you can write pipes and quotes. It starts in
  the folder of the focused pane.
- `description` is the name in the command palette and in
  `tuios keybinds list`. It is optional.
- `name` keeps a scratch terminal under a fixed name. It is optional. Without it,
  tuios makes the name from the description or the command. tuios uses only
  the first 40 characters, so two entries can get the same name. tuios then
  ignores the second entry, and `tuios keybinds doctor` shows it. Give one of
  the two entries a `name`.
- `width` and `height` set the size of a scratch or popup entry, in cells
  (`100`) or percent (`80%`). The default is `80%`.

The command gets these variables:

| Variable                | Value                                    |
| ----------------------- | ---------------------------------------- |
| `TUIOS_SESSION`         | The session in which you pressed the key |
| `TUIOS_SOCKET`          | The socket of the daemon                 |
| `TUIOS_ACTIVE_PANE_ID`  | The pane that had the focus              |
| `TUIOS_ACTIVE_PANE_CWD` | The folder in which the command starts   |

A command key never takes a key from a tuios action or from the leader key.
When the key is taken, `tuios keybinds doctor` shows the entry as dead. When
two entries have the same key, the first entry in `config.toml` runs, and the
doctor shows the other as dead. To move an entry to a different key, edit its
`key` in `config.toml`. The command palette lists each entry, and
`tuios keybinds list` shows them under Commands.

A key with no modifier and no `prefix+`, for example `g`, works in terminal
mode too. It takes that letter from every pane, so tuios shows a warning. Use
`prefix+g` or a key with a modifier, for example `alt+g`.

When a scratch command stops in its first moments, for example because the
program is not installed, the dock shows its exit code. The next press starts
it again. tuios does not start it again by itself.

The command and the palette row of an entry change when you save
`config.toml`. A changed key works at the next key press, as for the other
keybindings. When you remove or rename an entry, or change the description of
an entry that has no `name`, the panes of its scratch terminal close at the
next reload. The
dock shows a message.

In a session on a different machine, a `scratch`, `popup` or `pane` entry runs
on the machine of the session. The command runs as the user of that machine,
in the folder of the focused pane on that machine. A `~` in the command is the
home folder on that machine. A `popup` or `scratch` entry there needs `"open"`
in the `allow` list of that machine's `[hosts]` table for your machine. Without
it, the dock shows a message that names the table to change. A `shell` entry
runs on the machine that runs the tuios client.

Only a key press or the command palette runs a command key. A change to
`config.toml` does not run a command. A pane that has the respond grant can
press keys as you through `run-command`. It can press a command key, also from
a session on a different machine, and a `shell` entry then runs on this
machine. Give the respond grant only to a pane that you trust.

### Recipes

These are command keys for common tasks. Copy an entry into `config.toml` and
change the key to taste. Run `tuios keybinds doctor` after you add one, to
check the key is free.

**Per-session notes.** This scratch entry opens `$EDITOR` on a notes file
named after the session, and makes the notes folder first. It falls back to
`vi` when `$EDITOR` is not set.

```toml
[[keybindings.command]]
key = "prefix+alt+n"
type = "scratch"
command = "mkdir -p ~/notes && ${EDITOR:-vi} ~/notes/$TUIOS_SESSION.md"
description = "Session notes"
```

**Browser pane.** This scratch entry opens a page in terminal-browser. It
needs terminal-browser installed, and a terminal with kitty graphics.

```toml
[[keybindings.command]]
key = "prefix+alt+b"
type = "scratch"
command = "terminal-browser open https://example.com"
description = "Browser"
```

**lazygit.** This is the example at the top of this section. It opens lazygit
in the focused pane's folder.

```toml
[[keybindings.command]]
key = "prefix+alt+g"
type = "scratch"
command = "lazygit"
description = "Lazygit"
width = "80%"
height = "80%"
```

**Pick a file into the focused pane.** This popup runs `fzf` and types the
pick into the pane you came from, with
[`tuios send-text`](https://tuios.dev/docs/cli-reference/remote-control-commands#tuios-send-text) and the pane id from
`TUIOS_ACTIVE_PANE_ID`.

```toml
[[keybindings.command]]
key = "prefix+alt+p"
type = "popup"
command = "tuios send-text -w \"$TUIOS_ACTIVE_PANE_ID\" \"$(fzf)\""
description = "Pick a file"
```

**Open a project.** This popup runs `fzf` over the folders in `~/dev` and
switches to the session of the folder you pick. When the session does not
exist, [`tuios switch-session`](https://tuios.dev/docs/cli-reference/daemon-mode#tuios-switch-session) makes
it in that folder. See [Sessionizer](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#sessionizer).

```toml
[[keybindings.command]]
key = "prefix+alt+s"
type = "popup"
command = 'dir=$(find ~/dev -mindepth 1 -maxdepth 1 -type d | fzf) && tuios switch-session --create --cwd "$dir" "$(basename "$dir")"'
description = "Open a project"
```

**Copy the pane's folder.** This shell entry copies the focused pane's folder
to the clipboard. It tries `pbcopy`, then `wl-copy`, then `xclip`, and uses the
first one it finds.

```toml
[[keybindings.command]]
key = "prefix+alt+y"
type = "shell"
command = "printf %s \"$TUIOS_ACTIVE_PANE_CWD\" | (pbcopy || wl-copy || xclip -selection clipboard)"
description = "Copy pane folder"
```

## Your actions

An `[[actions]]` entry in config.toml is an action of your own, `user:NAME`.
A key, a menu row or `tuios actions run` runs it on the focused pane. It runs
one of three things:

| Field                                    | Runs                                                                                               |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `action = "new_window"`                  | A built-in action, as its key does                                                                 |
| `run = ["code", "{pane.cwd}"]` with `in` | A program and its arguments, in a `popup` (the default), a `pane`, a `scratch` pane, or `silent`ly |
| `plugin = "id.action"`                   | A plugin action                                                                                    |

```toml
[[actions]]
name = "open-in-editor"
label = "Open the folder in the editor"
key = "prefix+alt+e"
run = ["code", "{pane.cwd}"]
in = "silent"
```

`key` is written as a [command key](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#command-keys): `prefix+` puts it after the
leader, and any other key acts in window and terminal mode. You can also bind
`user:NAME` in any `[keybindings.*]` table.

A placeholder fills one argument from the focused pane: `{pane.id}`,
`{pane.cwd}`, `{pane.title}`, `{pane.program}`, `{session}`, `{workspace}`,
`{selection}` and `{host}`. Its text goes into the argument as it is. No shell
reads it, and a placeholder in it is not filled again, so a title such as
`$(rm -rf ~)` is only text. When you write a shell into `run`, tuios refuses a
placeholder inside the shell's script: put it after the script and read it as
`$1`.

```toml
[[actions]]
name = "save-title"
run = ["/bin/sh", "-c", "printf '%s\\n' \"$1\" >> ~/titles.txt", "save-title", "{pane.title}"]
in = "silent"
```

A command runs where a command key does: a popup, a pane and a scratch pane on
the session's machine, a silent command on this one. It has the command key
variables too (`TUIOS_SESSION`, `TUIOS_ACTIVE_PANE_ID` and the others).

A `[[keybindings.command]]` entry is an action of this kind as well:
`user:NAME` runs the command entry called NAME when no `[[actions]]` entry has
that name.

User actions are read from config.toml only. `tuios set-option`, which a pane
can call, cannot add or change one. From inside a pane, `tuios actions run`
needs the respond grant.

`tuios actions list` lists your actions, `tuios actions list NAME` shows one
(and why tuios ignores it, when it does), and `tuios actions run NAME --dry-run` prints the arguments it would
run, with the placeholders filled ([CLI\_REFERENCE.md](https://tuios.dev/docs/cli-reference/tuios-web#tuios-actions)).
A mistake in an entry is a warning, and tuios ignores that entry.

### Your menus

A menu is a `[menus.NAME]` table: a title and a list of rows. One menu shows
two ways. `open_menu:NAME` on a key opens it as a which-key panel of the rows
that have a `key` ([Menus nested under the leader](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#menus-nested-under-the-leader)).
The same action as a row of a right-click menu opens it in that menu's place.

The target names are reserved: `pane`, `selection`, `desktop`, `dock`,
`dock_item`, `workspace`, `session`, `repo`, `machine` and `file` are the
right-click menus tuios ships. Their table changes the shipped rows. You do
not copy them.

```toml
[menus.pane]
add = ["user:open-in-editor", { menu = "tools" }]
after = "toggle_zoom"
remove = ["screenshot_window"]

[menus.tools]
title = "Tools"
items = ["user:deploy", "---", "new_window"]
```

| Key      | Does                                                               |
| -------- | ------------------------------------------------------------------ |
| `add`    | Puts the rows after the row whose action is `after`, or at the end |
| `remove` | Removes the rows with these actions                                |
| `items`  | Replaces all the rows (the rows of any other menu)                 |
| `title`  | Heads a menu that is not a target's                                |
| `sticky` | Keeps the which-key panel open after a key runs                    |

A row is an action name, `"---"` for a separator, or a table:

| Row key            | Is                                                                  |
| ------------------ | ------------------------------------------------------------------- |
| `action` or `menu` | What the row runs: an action, or the menu `NAME` (`open_menu:NAME`) |
| `key`              | The key in the which-key panel, or a list of keys                   |
| `label`            | The row's text, in the place of the action's                        |
| `when`             | Shows the row only while the focused pane matches (see below)       |

A submenu row acts on the target of the first menu. A shipped action keeps
its label and its state (a dimmed row stays dimmed). Another built-in action
shows its description. A key on a target's row is not read: a target's menu
opens on its target.

A `user:NAME` row shows only on the targets in the action's `targets` (a pane
when it has none), and only while its `when` matches the focused pane:

```toml
[[actions]]
name = "explain-error"
targets = ["pane", "selection"]
when = { agent_state = ["idle", "done"], program = "claude" }
action = "copy_selection"
```

`when` reads `agent_state`, `harness`, `program`, `host` and `has_selection`
(`"true"` or `"false"`). Each value is a string or a list of strings, and the
fact must equal one of them. A row's own `when` works the same way, in a
right-click menu. The which-key panel shows every row that has a key.

## Master-stack layout

The layout prefix (`Ctrl+B L`) has keys for the master-stack layout. They act
on the workspace on screen.

| Keys                              | Action                               | What it does                                                             |
| --------------------------------- | ------------------------------------ | ------------------------------------------------------------------------ |
| `Ctrl+B L o`                      | `cycle_master_position`              | Move the master panes to the next side: left, right, top, bottom, center |
| `Ctrl+B L Enter`                  | `swap_with_master`                   | Swap the focused pane with the master pane                               |
| `Ctrl+B L m`                      | `focus_master`                       | Focus the master pane                                                    |
| `Ctrl+B L i`                      | `add_master`                         | Make one more pane a master pane                                         |
| `Ctrl+B L d`                      | `remove_master`                      | Make one pane fewer a master pane                                        |
| `Ctrl+B =`, or `=` in window mode | `equalize_splits`, `equalize_splits` | Give the master panes and the stack their default sizes again            |

The resize keys move the divider between the master panes and the stack. With
the master on the left, the right or in the center, the width keys move it,
such as `<` and `>` in window mode. With the master at the top or the bottom,
the height keys move it. The workspace keeps the new size.

`set_master_position_left`, `set_master_position_right`,
`set_master_position_top`, `set_master_position_bottom` and
`set_master_position_center` have no default key. To bind one, add it to a
section:

```toml
[keybindings.layout_prefix]
set_master_position_center = ["c"]
```

See [LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md#master-stack-layout).

## Ask before a pane closes

`x` in window mode (`close_window`), `Ctrl+B x` (`close_window`), the
pane menu's `Close pane` and the close control in the title bar close the pane
at once. To get a question first, set `appearance.confirm_close`:

```toml
[appearance]
confirm_close = "busy"   # never (default), busy or always
```

- `never` closes at once. This is the default.
- `busy` asks when the pane runs something besides its shell, such as an
  agent, an editor or a long job. A pane at its shell prompt closes at once.
- `always` asks for every pane.

The dialog names the pane. `Cancel` is the default row. Go down to
`Close pane` and press `Enter` to close it, or press `Esc` to keep it.
`tuios close-window` and the other commands never ask.

## Focus only

`Ctrl+B m f` (`minimize_prefix_focus_only`, in the `minimize_prefix` section)
minimizes every other pane on the workspace and keeps the focused pane. Press
it again to restore the panes it minimized. A pane that you minimized before
the first press stays minimized. A pane that you restored or closed in between
is skipped. The command palette has the entry "Focus only". Scratch panes and
popups are not minimized.

## Close every pane on a workspace

The `close_workspace` action closes every pane on the current workspace. It is
the same as tmux `kill-window`. Use it to close the panes that `tuios xpanes`
opened. The action has no default key. The command palette has the entry
"Close workspace". To bind it, add it to a section. This example uses
`Ctrl+B Alt+X`, because `Ctrl+B X` closes the session:

```toml
[keybindings.prefix_mode]
close_workspace = ["alt+x"]
```

The action asks first. The dialog names the workspace and shows how many panes
close and how many agents are in them. `Cancel` is the default row. Scratch
panes stay open.

Right-click a workspace tab in the dock to close that workspace, whether or not
it is the one on screen. The tab's menu has the rows `Switch to`, `Rename` and
`Close`. `Close` is the same `close_workspace` action as the key and the palette
entry, with the same dialog, but it acts on the tab's workspace instead of the
current one. It is dimmed when the workspace has no pane to close. Closing a
workspace that is not on screen leaves the view where it is.

When the closed workspace is not on screen, or when tuios goes back from it,
the workspaces above it move down one, so the numbers follow the positions.
See [CONFIGURATION.md](https://tuios.dev/docs/configuration/workspaces-and-windows#workspace-numbers).

`tuios close-workspace` does the same from a shell. See
[CLI\_REFERENCE.md](https://tuios.dev/docs/cli-reference/remote-control-commands#tuios-close-workspace).

## Restart the daemon

The `restart_daemon` action stops the daemon and starts it again with the
newest tuios installed. Use it after an update. The action has no default key.
The command palette has the entry "Restart the daemon". These open it too:

- The notice that says the daemon and this window run different versions,
  for example "The daemon runs 0.10.0. ctrl+b j restarts it." Click it, or
  press the key it names. Press `esc` to put it off until the next start.
- The row "Restart the daemon" at the top of the Daemon tab in the settings.
- The rail's menu for this machine.

A dialog shows the daemon's version now and after the restart, and this
window's version when it moves too. It lists the programs that stop, by pane
and session, and what comes back, with the agents that can resume. The text
is the text `tuios restart-server` prints. Press `r` to restart, or `esc` to cancel. A click on a row
does the same. When the list is taller than the screen, it scrolls and the
answers stay at the bottom. Use `PgUp`, `PgDn`, `Home`, `End` or the wheel. The dialog then shows each step: stop the daemon, start the new
one, attach again. tuios then starts again on the new build, in the same
session, and says "The daemon restarted on 0.10.2. Your session is back."

Other clients attached to the daemon wait up to 15 seconds for the new one.
They then attach to their session again by themselves and say "The daemon
restarted. tuios reattached." While they wait, the dock says "Waiting for the
daemon. Keys are not sent." With the dock hidden, the middle of the screen
says it. Keys typed then are not sent to the panes.

A live upgrade (`tuios daemon upgrade`) drops the clients the same way, and
they wait for the new image and attach again by themselves, saying "The
daemon was upgraded. tuios reattached." When the new image is a newer
build, the client runs that build instead, on the same terminal and session,
and says "The daemon was upgraded to \<version>. This window runs it too."
A client whose build speaks another wire protocol than the new image and is
not older than it exits instead and says how to attach again.

When a step fails, the dialog says what happened and what to do next. When
a program started or stopped after you agreed, the restart does not run, and
the dialog asks you to read the new list. When your session did not come
back, tuios does not attach to it: the dialog says so and points to
`tuios resurrect`. When
the daemon did not start, the row is "Quit tuios", and tuios prints the same
words when it quits. To bind the action:

```toml
[keybindings.prefix_mode]
restart_daemon = ["alt+r"]
```

`tuios restart-server` does the same from a shell. See
[CLI\_REFERENCE.md](https://tuios.dev/docs/cli-reference/daemon-mode#tuios-restart-server).

## Move a pane to another workspace

Three default key sets go to workspace N or send the focused pane there. They
work in window mode and in terminal mode.

| Action                                         | macOS         | Linux and other | What it does                                                                                        |
| ---------------------------------------------- | ------------- | --------------- | --------------------------------------------------------------------------------------------------- |
| `switch_workspace_1` to `switch_workspace_9`   | `opt+N`       | `alt+N`         | Shows workspace N.                                                                                  |
| `move_and_follow_1` to `move_and_follow_9`     | `opt+shift+N` | `alt+shift+N`   | Sends the focused pane to workspace N and shows workspace N.                                        |
| `send_to_workspace_1` to `send_to_workspace_9` | `ctrl+opt+N`  | `ctrl+alt+N`    | Sends the focused pane to workspace N and stays on this workspace. Focus goes to another pane here. |

`send_to_workspace_N` needs a terminal that reports Ctrl and Alt with a digit.
A legacy terminal sends `ctrl+alt+N` as `alt+N`, or as a control character for
most digits. The Kitty keyboard protocol reports the key, and so does xterm's
modifyOtherKeys. Ghostty, kitty, WezTerm and foot speak the Kitty protocol. In
another terminal, bind the action to a key the terminal can send:

```toml
[keybindings.workspaces]
send_to_workspace_2 = ["alt+w"]
```

Your `config.toml` may already bind `ctrl+alt+N` to another action in window
mode. Then that binding keeps the key, and `send_to_workspace_N` has none.
`tuios keybinds doctor` lists it.

Windows sends AltGr as Ctrl+Alt. A character typed with AltGr, such as `€` on a
UK keyboard, still reaches the pane and does not move it.

## Cycle through workspaces

The `next_workspace` and `prev_workspace` actions go to the next or the
previous workspace that has panes, and wrap at the end. They skip a workspace
with no panes, so with `workspaces.new_window_when_empty` on they do not open
a pane on each empty workspace. When no other workspace has panes, they do
nothing. The actions have no default key. The command palette has the entries
"Next workspace" and "Previous workspace". To bind them:

```toml
[keybindings.workspaces]
next_workspace = ["alt+y"]
prev_workspace = ["alt+u"]
```

## Cycle through machines

The `next_host` and `prev_host` actions go to a session on the next or the
previous machine. The order is the order of the machine groups in the rail.
This machine is first, then the machines of the `[hosts]` table. The actions
wrap at the end. They skip a machine whose link is not up and a machine with
no session.

On each machine, they go to the session you last showed on that machine. If
you have not been on that machine, or that session is gone, they go to the
session that is attached there. If no session is attached, they go to the first
session in the rail. With no other machine, they show "No other machines".

The actions have no default key. The command palette has the entries "Next
machine" and "Previous machine". To bind them:

```toml
[keybindings.window_management]
next_host = ["alt+."]
prev_host = ["alt+,"]
```

Like `next_session`, a chord with Alt or Ctrl also works in terminal mode.

## Actions for a tmux-style keymap

These actions have no default key. Bind them in any
section where you want them.

| Action                                                                                | What it does                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mark_pane`                                                                           | Marks the focused pane, or clears the mark when it is the marked one. The marked pane shows `[marked]` in its title bar.                                                                                                       |
| `join_marked_left`, `join_marked_right`, `join_marked_up`, `join_marked_down`         | Moves the marked pane next to the focused one, on that side, from this workspace or another. Needs BSP tiling.                                                                                                                 |
| `resize_pane_left_5`, `resize_pane_right_5`, `resize_pane_up_5`, `resize_pane_down_5` | Moves the focused pane's edge by 5 cells. The `_20` actions move it by 20. Under the leader, the key repeats without a second leader press, as tmux `bind -r` does.                                                            |
| `new_workspace`                                                                       | Goes to the first workspace with no pane, the one the dock's `+` button opens, and opens a pane there. On an empty workspace past the last one in use, that workspace is the new one: it stays there and opens the pane there. |
| `last_workspace`                                                                      | Goes back to the workspace you were on before this one, as tmux `last-window` does. Press it again to go back and forth.                                                                                                       |
| `break_pane`                                                                          | Moves the focused pane to the first workspace with no pane and goes with it, as tmux `break-pane` does.                                                                                                                        |
| `last_session`                                                                        | Goes back to the session you were on before this one, as tmux `switch-client -l` does.                                                                                                                                         |
| `send_prefix`                                                                         | Sends the leader key to the program in the focused pane, as pressing the leader two times in terminal mode does. Use it for screen's `C-a a`, or for a tmux in the pane.                                                       |
| `move_workspace_left`, `move_workspace_right`                                         | Swaps this workspace with the one before or after it, and follows it. The two workspaces trade numbers, so the moved one answers to its new number.                                                                            |
| `cycle_layout`                                                                        | Cycles BSP, master-stack and scrolling.                                                                                                                                                                                        |
| `reload_config`                                                                       | Reads `config.toml` again, as the "Reload config" palette row does.                                                                                                                                                            |
| `toggle_mouse`                                                                        | Stops asking the terminal for mouse reports, so the terminal selects text itself. Run it again to turn the mouse back on. The setting lasts until you quit.                                                                    |

For tmux's synchronize-panes, bind `toggle_multifocus_all`. It puts every pane
on the workspace in the multifocus set, so typing goes to all of them. See
[LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md#multifocus).

```toml
[keybindings.window_prefix]
mark_pane = ["m"]
join_marked_right = ["J"]
```

## Menus nested under the leader

A key in a prefix menu can open a menu of your own, so a keymap can nest as
deep as a tmux which-key tree. You declare the menu ([Your menus](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#your-menus)),
give its rows a `key`, then bind the action `open_menu:NAME` to the key that
opens it. tuios has no menus of this kind until you declare one, and it binds
no new key for them.

```toml
[keybindings.window_prefix]
"open_menu:split" = ["s"]

[menus.split]
title = "Split"
items = [
  { action = "split_vertical", key = "y" },
  { action = "split_horizontal", key = "x" },
  { menu = "resize", key = "R" },
]

[menus.resize]
title = "Resize"
sticky = true
items = [
  { action = "resize_pane_left_5", key = "h" },
  { action = "resize_pane_down_5", key = "j" },
  { action = "resize_pane_up_5", key = "k" },
  { action = "resize_pane_right_5", key = "l" },
]
```

`Ctrl+B t s y` splits the pane. `Ctrl+B t s R h h h` narrows it by three steps.

- `open_menu:NAME` goes in any section: after the leader, in another menu, or
  in window mode or terminal mode for a menu that opens on one key.
- A menu name has lowercase letters, digits, `-` and `_`.
- `title` heads the which-key panel and defaults to the name. `sticky` keeps
  the menu open after a key runs, as tmux `bind -r` does, until `esc` or a key
  the menu does not bind. In terminal mode that key goes to the pane, so the
  first letter you type after resizing is not lost. `esc` and `ctrl+c` close a
  menu and are never sent to the pane.
- A key that the menu does not bind closes it, and a menu that is not sticky
  drops the key, as the other prefix menus do.
- The which-key panel lists the keys the menu has. Menus come first, marked
  with `›` at the right, as a right-click menu marks a row that opens a menu.
- `tuios keybinds list`, `doctor`, `unbind` and `free` read the menus as they
  read any other section, named `menus.NAME`. A config warning names a key
  that opens a menu that is not declared, a menu that nothing opens, and a
  menu key whose action the overlay it opens over does not have (see below).
- `[keybindings.menus.NAME]`, with `title`, `sticky` and a `keys` table of
  `action = ["key"]`, is the older spelling of a menu and is still read: its
  keys are the rows. When both spellings declare one name, tuios uses
  `[menus.NAME]` and warns.

### Menus in the rail, the Inbox and the other overlays

`open_menu:NAME` also works in the sections of an overlay: `sidebar`,
`sidebar_files`, `sidebar_agents`, `quick_look`, `quick_look_inside`, `inbox`,
`inbox_peek`, `mail`, `transfers` and `review`. The menu opens over the
overlay, and its keys run that overlay's own actions, so name actions of the
same section.

```toml
[keybindings.inbox]
"open_menu:triage" = ["x"]

[menus.triage]
title = "Triage"
items = [
  { action = "inbox_dismiss", key = "d" },
  { action = "inbox_snooze", key = "s" },
  { action = "inbox_close", key = "c" },
]
```

In the Inbox, `x d` dismisses the selected item and `x c` closes the Inbox.
`esc` closes the menu and leaves the overlay open, and the next key is the
overlay's own again. A menu that the overlay's menu opens runs over the same
overlay. A sticky menu stays open while the overlay does. Copy mode is not one
of these sections: bind its menus in `terminal_mode` or under the leader.

## Split into the same ssh

These actions open a pane on the machine that the focused pane is connected to
with ssh:

| Action                 | What it does                    |
| ---------------------- | ------------------------------- |
| `split_ssh_horizontal` | Splits the pane top and bottom. |
| `split_ssh_vertical`   | Splits the pane left and right. |
| `new_window_ssh`       | Opens a new window.             |

The new pane runs ssh again, to the same destination as the same user, with the connection options only.
tuios does not run the remote command again. It also removes `-N`, `-f`, `-T`,
`-W`, port forwards and the other options that stop a shell. `mosh` works the
same way.

When the focused pane does not run ssh, the action opens an ordinary pane. You
can use the keys in every pane. Some ssh lines also get an ordinary pane. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/display-mouse-and-shell#lines-that-are-not-followed).

The actions have no default key. The command palette has an entry for each
one. To bind them, add them to a section. This example uses keys for
window-management mode:

```toml
[keybindings.layout]
split_ssh_vertical = ["alt+v"]
split_ssh_horizontal = ["alt+s"]
new_window_ssh = ["alt+w"]
```

To make the ordinary split and new-window keys do the same, set
`appearance.new_window_follow_ssh`. To start the new pane in the remote
folder, make the remote shell report its folder. See
[CONFIGURATION.md](https://tuios.dev/docs/configuration/display-mouse-and-shell#splits-that-follow-ssh).
