Keybindings

TUIOS has two modes. Window mode is for managing panes. Terminal mode sends your keys to the focused pane. A new session starts in window mode.

The leader key is Ctrl+B. Press it, release it, then press a command key. The leader works in both modes.

To send the leader key to the program in the pane, press it two times in terminal mode. The pane gets the leader that you configured, such as Ctrl+A.

Every table on this page names the config section that holds the binding and the action name to use in it. Every action is rebindable. See Customizing at the end.

Try it live: Learn tuios has you press these keys in the real app, in your browser. Free play has a cheat sheet you can click.

Search every default binding, or read the tables by section below:

Modes

Section: [keybindings.mode_control]. These keys work in window mode.

To leave terminal mode, press Ctrl+B Esc, or the direct key from Terminal mode.

hold_window_mode needs a terminal that speaks the Kitty keyboard protocol (Ghostty, kitty, WezTerm, foot, Alacritty), because only that protocol reports key releases. Bind it to an ordinary spare key, such as an unused function key from f1 to f12. Binding a modifier such as leftalt also works, but then every keystroke in the session arrives as an escape code.

Window mode

Windows

Section: [keybindings.window_management].

Section [keybindings.restore_minimized] restores one minimized window by position:

Section [keybindings.system] has one binding: B is toggle_spotlight, which lights one part of the screen and dims the rest. See Spotlight.

Workspaces

Section: [keybindings.workspaces]. There are nine workspaces. The modifier is Option on macOS and Alt elsewhere.

rename_workspace opens the rename editor on the current workspace. It has no default key. Ctrl+B w r does the same from the prefix.

Cycle through workspaces Added in v0.9.3

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:

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

Layout and snapping

Section: [keybindings.layout].

resize_master_shrink_left has no default because , opens settings. Bind it to a free key if you want it.

Corner snapping is on the layout prefix, not on the bare digits.

Moving focus

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

Focus goes to the nearest window in that direction that faces the focused window. At the edge of a tiled layout, focus stays where it is, unless appearance.focus_wrap Added in v0.12.0 is on. Then focus goes to the window on the far side that faces the focused window. With tiling off, a window that does not face the focused window can also get focus.

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.

In the scrolling layout, left and right move between columns. Up and down move between the windows in one column.

The terminal mode keys and the prefix keys go on into the rail. When no window is in that direction and the rail is on that edge, the rail gets the keyboard. The key in the opposite direction gives the keyboard back. A hidden rail stays hidden.

If your config already binds j or k in a window mode section, TUIOS keeps your binding and gives focus_down or focus_up no key. tuios keybinds doctor tells you when this happens.

Neovim pane navigation

The optional tuios-nvim-navigator plugin lets the terminal-mode focus keys move through Neovim splits first. At the edge of a split, TUIOS moves to the next pane. The feature is off by default. Turn it on:

[appearance]
nvim_navigation = true

The plugin tells TUIOS when it is active, so the same keys keep their normal TUIOS action in shells and other programs. By default, both projects use Alt+←, Alt+↓, Alt+↑ and Alt+→. If you change the keys on one side, change the other to match terminal_focus_left, terminal_focus_down, terminal_focus_up and terminal_focus_right.

The plugin sends private OSC 7777 messages. TUIOS reads them and never shows them in the pane:

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. Another Neovim integration can send the same messages. TUIOS accepts a focus request only from the focused pane in terminal mode, and only just after it sent the matching focus key to that pane. Window mode always keeps the focus keys for TUIOS.

See also: the Neovim page.

BSP splits

Also in [keybindings.layout]. See BSP Tiling.

The preselect keys use Option on macOS. The prefix menu has its own copies of the four split actions, and rebinding one set does not change the other.

Terminal mode

Section: [keybindings.terminal_mode]. These keys work in terminal mode with no prefix. Everything else goes to the pane.

Plain Ctrl+V is not bound. It reaches the pane, so vim's visual block mode works.

Shift+↑ and Shift+↓ scroll the pane into its history only when the program is on the main screen and did not turn on a mouse mode. In other panes, TUIOS sends the keys to the program, so nvim, less and htop get them. In copy mode the keys scroll. This is the same rule as for the mouse wheel, and the same rule as in kitty. Shift+PgUp and Shift+PgDn follow the same rule, and scroll one page of the pane at a time.

Middle-click paste Added in v0.10.0

In terminal mode, a middle click pastes from the clipboard. It does not paste the primary selection. A program that uses the mouse, such as vim with mouse=a, lazygit or tmux, gets a plain middle press. In [keybindings.terminal_mode], middle names the middle button. It takes ctrl, alt and shift, such as ctrl+middle. A binding with a modifier works over a program that uses the mouse too. Other tables do not accept middle.

[keybindings.terminal_mode]
# Paste only on ctrl+middle, and give the plain middle click to every program
terminal_paste_host = ["ctrl+shift+v", "super+v", "shift+super+v", "ctrl+middle"]

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 key also pastes an image. When the clipboard holds an image and no text, the paste key pastes the image. When the clipboard holds text, the paste key 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:

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 paste folder next to the TUIOS socket keeps at most 50 images and 100 MB. When it is full, TUIOS deletes the oldest image.

A pane on another machine Added in v0.9.3

TUIOS writes the image on the machine where the pane program runs. A pane can run on another machine in three ways:

• 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 a machine in your [hosts] table, 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 it does for a pane that only reports a folder on another machine and runs no ssh.

TUIOS does not read the clipboard when the client runs in a browser, when it runs on another machine through tuios ssh, or when the paste comes from send-keys. Inside ssh, TUIOS reads only an X display that ssh -X forwards. Any other clipboard there is the other machine's.

Keys sent to the pane are encoded the way a real terminal encodes them. When the program in the pane turns on application cursor keys (DECCKM), as zsh's line editor does, the arrows, Home and End are sent in their SS3 form (ESC O H for Home) instead of the CSI form (ESC [ H), so the program's bindings for them work. tuios send-keys follows the same rule.

tuios send-keys also encodes a named key or a chord in the keyboard mode the program asked for. A program that asked for the kitty keyboard protocol or modifyOtherKeys gets that encoding, the same as for a key you press. Vim then reads Ctrl+H as Ctrl+H, not as Backspace.

Copies between machines Added in v0.9.3

Ctrl+B u opens the Copies panel. It shows one row for each copy between machines, newest first. The dock item transfers opens it with a click. The command palette row is "Copies between machines". Nothing shows in the dock or on the rail while no copy exists.

A running copy also shows a percent mark on the rail row of its machine.

The keys are in [keybindings.transfers]. The panel key is prefix_transfers in [keybindings.prefix_mode]. A notice shows when a copy ends.

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.

Send files to another machine

• In the files list of the rail, the menu of a file has Send to machine. It copies the file to the receive folder of the machine you pick.
• 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 does not change.

See tuios cp and Copy files between machines.

Lock mode Added in v0.11.0

Lock mode gives every key to the program in the pane. It is the locked mode of zellij. Turn it on in config.toml:

[keybindings]
lock = true

The zellij preset turns it on, with Ctrl+G as the leader. Set lock = false to turn it off under that preset.

• In terminal mode, TUIOS takes only the leader. Every other key goes to the pane, also the keys that TUIOS binds. Alt+1 to Alt+9, Alt+n, Alt+Esc, Ctrl+P, the arrow keys with Alt, Shift+↑ and the hold key all go to the pane.
• The leader unlocks. Press the leader, then the keys of one action. The action runs and TUIOS locks again.
• A repeatable action keeps its menu open. These are the actions in keybindings.repeat, such as focus moves and resize steps. Press the key again to move again. You do not press the leader again.
• The open menu then takes only repeatable keys. Any other key closes the menu, goes to the pane, and TUIOS locks again. For example, x after Ctrl+B ← → goes to the pane. It does not close a pane. The which-key panel of the open menu shows only the repeatable keys and Esc.
• Press Esc to close the menu and lock again. Ctrl+C also closes it.
• Press the leader to close the menu and open a new leader menu.
• To go to window mode, press the leader, then Esc.
• To send the leader to the pane, press the leader two times.
• Window mode, overlays, copy mode and the mouse do not change.

The mode pill in the dock shows a lock while TUIOS is locked. It shows an open lock while the leader or a menu waits for a key. Without Nerd Fonts, the pill shows LOCK and UNLOCK. When the dock is hidden, or appearance.dock_prefix_indicator is "badge", the floating badge shows PREFIX and the open lock while a menu waits for a key.

Nest mode Added in v0.12.0

Nest mode gives every key to the program in the pane, the leader too, until you press one key to end it. Use it for a tmux, or a tuios on another machine, that uses the same leader. The nest action turns it on. Its default key is Ctrl+B Enter, in every preset.

[keybindings.terminal_mode]
nest = ["alt+shift+enter"]

• In terminal mode, every key goes to the focused pane: the leader, the keys tuios binds and the hold key.
• F12 ends nest mode and does not go to the pane. keybindings.nest_exit_key Added in v0.12.0 sets another key. A key tuios cannot read goes back to F12, and the log viewer reports a key that programs type, such as a letter.
• Overlays that you open with the mouse, copy mode and the mouse do not change.
• While the rail has the keyboard, the rail takes the keys. Press Esc to give them back to the pane.
• Nest mode belongs to the client. It ends when the client leaves terminal mode, and on detach.

The mode pill in the dock shows NEST F12, and the focused pane's border takes the same colour.

Global keys

Section: [keybindings.global]. These keys work in window mode and terminal mode.

The command palette searches commands, sessions and windows. Start the query with @ to filter panes by agent state (@n for needs input), or with # to search actions to rebind. Each row shows the key you bound to its action, such as prefix+a, and no key when the action has none. A change to the config shows the next time you open the palette.

The app launcher lists every executable on $PATH, ranked by use. Enter runs the selection in a new pane with no shell in between. Tab types the command into the focused shell instead, so you can add arguments.

These two keys take Ctrl+P from fish and vim and Alt+Space from readline. Set an action to [] to give its key back. On macOS, Option+Space types a non-breaking space, so use Ctrl+B a for the launcher.

Prefix commands

Press Ctrl+B, then the key. Section: [keybindings.prefix_mode].

In terminal mode, pressing the leader twice sends one literal Ctrl+B to the pane.

The which-key popup that opens after the leader shows the keys of your config. A key that you rebind shows in its new place. An action that you unbind has no row. A row for a range of keys, such as 1-9, shows only the keys that are bound. For example, if you unbind the key for workspace 5, the row shows 1-4/6-9. Set appearance.whichkey_enabled = false to turn the popup off.

After a command worth repeating, such as an arrow, o or O, the prefix stays armed for 500 ms. Ctrl+B then ← ← ← moves three panes. Change this with appearance.prefix_repeat_time. 0 turns it off.

Scratch terminal

Ctrl+B g shows the scratch terminal, a small layout of panes in a box over the current layout. Press it again, also from inside the box, to hide it. 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. [scratch] sets the size of the box. See Scratch terminal.

New worktree Added in v0.11.1

Ctrl+B U makes a worktree of the repository of the focused pane's folder.

1. A small dialog asks for the branch name.
2. Optionally, press Tab and type a session name. With no name, TUIOS uses the name the dialog shows.
3. Press Enter. TUIOS makes a new branch in a new worktree, and a session in it. The rail groups the session under its repository, and TUIOS switches to it.

Esc closes the dialog. If the focused pane is not in a git repository, a message says so. This is what tuios worktree new does. The command palette has the action too. See Worktrees.

Session note Added in v0.12.0

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 command palette and the menu of a session row in the rail have it too. See Return notes.

Pick a path Added in v0.12.0

Alt+; in terminal mode (Option+; on macOS), or Ctrl+B ., opens the path picker at the cursor of the focused pane. The picker lists the folder that the shell in the pane is in. Folders come first, then files. Type to filter the names, and press Enter to type the path of the selected name at the cursor.

The path is relative to the folder of the pane. A path that starts with / or ~/ stays absolute. tuios quotes the path for the shell in the pane. A click on a name types its path, and the wheel moves the selection.

The picker works in a pane on another machine: the daemon there lists the folder, with the same read rules as the files section. When the shell in the pane runs ssh to another machine, the picker does not open. path_picker.show_hidden Added in v0.12.0 shows the hidden files when the picker opens.

Calm mode Added in v0.12.0

Ctrl+B Z turns calm mode on and off. While calm mode is on:

• Nothing moves. Window slides, panel fades, the shimmer of a working agent 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. To keep calm mode on after a restart, set appearance.calm = true. See Calm mode.

Window prefix

Ctrl+B t, then the key. Section: [keybindings.window_prefix].

Minimize prefix

Ctrl+B m, then the key. Section: [keybindings.minimize_prefix].

Workspace prefix

Ctrl+B w, then the key. Section: [keybindings.workspace_prefix].

Layout prefix

Ctrl+B L, then the key. Section: [keybindings.layout_prefix].

Actions resize_width_10 to resize_width_40 and resize_height_10 to resize_height_40 also exist, with no default key.

Loading a layout moves the existing windows into place. It does not close any. Extra windows are minimized. tuios layout manages saved templates from the shell.

Tape prefix

Ctrl+B T, then the key. Section: [keybindings.tape_prefix]. See Tape Recording.

While a tape plays, section [keybindings.script] is active: Ctrl+P is script_pause and pauses or resumes playback.

Debug prefix

Ctrl+B D, then the key. Section: [keybindings.debug_prefix].

Session rail

Section: [keybindings.sidebar]. Active while the rail has the keyboard: press s in window mode, or Ctrl+B e.

When the cursor is on a row in the files section, section [keybindings.sidebar_files] answers first:

See The files section.

When the cursor is on an agent row, section [keybindings.sidebar_agents] answers first. So r and x act on the agent there, and keep their rail meaning on every other row:

Enter on the +N at rest line shows the agent rows folded there.

Inbox and mailbox

The agents view shows every agent, and the Inbox items are its Needs you group. Open it with Ctrl+B i. Its keys are in [keybindings.inbox]:

With marks, r replies to each marked agent, 1 lists the approvals to allow, 3 rejects them, d dismisses and z snoozes. See Many agents at once.

A key new in the agents view yields to your own: when your [keybindings.inbox] already gives n, R, a, x or another new key to an action, that action keeps it. tuios keybinds doctor lists each one. A config that kept the old default inbox_deny_reason = ["n"] moves it to R, so n starts a new agent.

On an approval the Inbox holds for you, 1 allows it once, 2 always allows it and 3 rejects it. On a question put with ask-human, a digit picks that answer. The digits are not bindings.

The prompt that Space opens has its own section, [keybindings.inbox_peek]:

A digit chooses that numbered option of the prompt.

The mailbox (m in the Inbox) uses [keybindings.mail]: j/k (mail_down, mail_up), PgDn/PgUp (mail_page_down, mail_page_up), Enter opens a thread (mail_open), r replies (mail_reply), o goes to the pane (mail_focus_pane), n writes a new message to an agent (mail_new) and Esc or q goes back (mail_back).

The reply editor and the message editor take every key. Enter sends, Ctrl+J or Shift+Enter adds a line, Ctrl+V attaches the clipboard image, @ names an agent, a pane or a file, ↑ and Ctrl+R bring back an earlier reply, and Ctrl+G opens $EDITOR. These keys are not bindings. The full list is in The reply editor.

The footers name whatever key your config binds. Until an agent has been seen, the prefix menu, the help and the palette leave out the agent keys and entries, so a person who runs no agents is not shown them. The keys work before that too, except Ctrl+B O, which types O into the pane until then.

Next and previous agent Added in v0.12.0

next_agent and prev_agent go to the next or previous agent pane, in the order the rail's agents section lists them. They wrap at the ends. From a pane with no agent, they go to the first and the last. An agent in another session or workspace is switched to.

The default keys are Alt+Shift+J and Alt+Shift+K (with Option on macOS), and Ctrl+B J and Ctrl+B K. The chords also work in terminal mode and while the rail has the keyboard.

The review overlay

Ctrl+B v, or v in the Inbox or on a rail agent row, opens the diff of a pane's changes over the whole screen. See Reviewing an agent's changes. These keys are fixed and are not in the config.

The compare view lists the attempts of a fan. j/k move, Enter reviews an attempt, m marks one and d diffs the two marked attempts, V runs a command in every attempt, K keeps the attempt under the cursor and removes the others after a y, and Esc, q or w go back to the review.

A stage key changes only the index of the pane's worktree. The working files do not change. A hunk header shows staged when the index holds all of the hunk, and partly staged when it holds some of it. a stages only the lines of the hunk you see. When git splits those lines into two hunks of the index, the first a stages one part. Press a again to stage the rest. The keys do nothing in a comparison of two attempts.

The hunk and file motions and the stage keys are in [keybindings.review] Added in v0.12.0. A key you bind there wins over the overlay's own key. tuios warns when a review key is one of the overlay's own keys, and tuios keybinds doctor lists it under REVIEW KEYS. The other keys of the overlay are fixed.

[keybindings.review]
review_next_hunk = ["n"]
review_prev_hunk = ["p"]
review_next_file = ["N"]
review_prev_file = ["P"]

Lists and the settings page

Every list moves the same way: the palette, the launcher, the settings page, the Inbox, the mailbox, the keybind manager, the pickers, the switchers, the menus and the tape manager.

Set appearance.wrap_lists = false to stop at the ends instead of wrapping.

List keys Added in v0.10.0

The movement keys are in the [keybindings.lists] section. Each action takes the keys that do it:

A key that is one printable character is a letter key. Only a list with no filter to type into reads it. A list with a filter keeps its letters for the filter. To move on Ctrl+J and Ctrl+K as well as the arrows:

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

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

The settings page (, in window mode, or Ctrl+B ,) reopens on the tab, row and search you left it on:

A row whose value differs from its default has a dot after its name, including the hand-drawn rows such as the theme and shared borders, which have no reset. See The in-app settings page for the search.

The key hints at the foot of a panel stay on one row. When they do not fit, they get shorter 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.

Delete a word

Alt+Backspace, Ctrl+W and Ctrl+Backspace delete the last word of a short text field, such as a filter or the rename dialog. The keys skip the characters at the end that are not part of a word, then take the word. A word is letters, digits and _. So src/dir1/dir2 becomes src/dir1/, then src/, then nothing.

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, so a narrow screen shows fewer keys and never part of one. The main action and the way out always show. In hints mode, ? shows all of its keys in the help. A message that arrives while a mode is open shows in place of the keys until the message goes. The dock component is copy-help.

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. A key press, the terminal losing focus, or 60 seconds ends the hold.
• 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.

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.

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. The key was b in earlier versions.

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

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 prefix_toggle_spotlight. [spotlight] sets the size and the dimming. See Themes.

Close every pane on a workspace

The close_workspace action closes every pane on the current workspace, like tmux kill-window. Use it to close the panes that tuios xpanes opened. It has no default key. The command palette has the entry Close workspace. This example binds it to Ctrl+B Alt+X, because Ctrl+B X closes the session:

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

The action asks first. The dialog shows how many panes close and how many agents are in them. Cancel is the default row. Scratch panes stay open. tuios close-workspace does the same from a shell.

Split into the same ssh

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

The new pane runs ssh again, to the same host as the same user. It keeps the connection options, such as the port, the identity file and the jump host. tuios does not run the remote command again. It also removes -N, -f, -T, port forwards and the other options that stop a shell. mosh works the same way. Eternal Terminal (et) is not followed.

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.

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:

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

Copy mode

Press Ctrl+B [ to enter copy mode. It moves a cursor through the scrollback with vim keys. These keys are fixed and are not in the config, except Home and End. You can add keys that pipe a yank through a command. See Pipe a yank through a command. Put a count before a motion to repeat it: 10j, 5w.

The copy cursor starts on the terminal cursor, which is usually the prompt line. tmux does the same. To start on the middle row, set appearance.selection.copy_entry to center.

When the focused pane is in the multifocus set, Ctrl+B [ starts multi copy mode on every pane of the set.

The scrollback browser (Ctrl+B s) is a different tool. It lists past commands by their prompt marks, for shells that emit OSC 133.

A yank in copy mode also adds a paste buffer. Ctrl+B ] pastes it again.

Clear the scrollback Added in v0.11.0

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.

• 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 daemon session, the daemon clears the pane. Each client of the session shows the clear. A later attach 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.

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 that section works in terminal mode and in window mode:

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

Then tell the host terminal to send Cmd+K to TUIOS. In Ghostty, add keybind = cmd+k=unbind to the Ghostty config. 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:

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

tuios clear-history Added in v0.11.0 clears the scrollback from a script, as tmux clear-history does. See the CLI reference.

Leave copy mode, and other keys

• Ctrl+C leaves copy mode from normal mode, a selection, the search prompt or f/t. Nothing is copied.
• In a v or V selection, o moves the copy cursor to the other end of the selection. The selected text does not change. If the other end is outside the pane, the pane scrolls to show it.
• terminal_focus_left, terminal_focus_right, terminal_focus_up and terminal_focus_down also work in copy mode. In window mode, the window mode focus keys work. Focus moves to the next pane, and the old pane stays in copy mode. A focus key that copy mode also uses keeps its copy mode action. A key under the leader does not work in copy mode, because copy mode uses Ctrl+B for page up.

Line start and line end

Home moves the copy cursor to the start of the line, as 0 does. End moves it to the end of the line, as $ does. Both keys also move the end of a v or V selection. The help lists them next to 0 ^ $.

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.

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:

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

Search

The prompt shows / or ? for 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 also start at the copy cursor. After you move the cursor, they find the nearest match. When a search finds more than 1000 matches, the prompt shows 1000+.

Two actions start copy mode and open the search prompt with one key. They have no default key.

They do the same as tmux bind-key b copy-mode \; send-keys ?. Bind one in any section. This example puts the backward search on Ctrl+B /:

[keybindings.prefix_mode]
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, only a key in the global, terminal_mode or window_management section starts the action. A key after the leader does not, because copy mode uses Ctrl+B for page up. In copy mode, / and ? open the same prompts.

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.

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.

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

The clipboard gets the selection itself in these cases:

• The command writes nothing. Use this for a command that sends the text to a socket or a file.
• 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 also puts each yank in the X primary selection:

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

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

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

Mouse

In floating mode, drop a window on a screen edge to snap it: the left or right edge for a half, a corner for a quarter, the top center for the full screen.

In copy mode, a click moves the cursor and a drag selects. Dragging past the top or bottom of the pane scrolls.

Ctrl+drag still moves the pane. A link opens only when the pointer does not move. appearance.link_click sets which click opens a link.

Command keys

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

[[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.
• 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.
• 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:

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 or popup entry does not run. The dock shows a message. A pane entry runs on the machine of the session. 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.

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

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

[[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 and the pane id from TUIOS_ACTIVE_PANE_ID.

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