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.

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

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.

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.

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.

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.

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.

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.

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 Inbox lists everything waiting for you in every session. Open it with Ctrl+B i. Its keys are in [keybindings.inbox]:

On an approval the Inbox holds for you, 1 allows it once, 2 always allows it and 3 denies 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 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.

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.

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.

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.

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.

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"

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 makes it in that folder. See Sessionizer.

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

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

Customizing

Bindings live in 23 sections under [keybindings] in config.toml. Each action takes a list of keys.

[keybindings]
leader_key = "ctrl+a"

[keybindings.window_management]
new_window = ["n", "ctrl+t"]
close_window = []          # unbind: the key goes back to the pane

An empty list and a missing line are different. A missing action gets its default back at the next load. An empty list stays empty. Key syntax and every section are on the Configuration page.

The [keybindings] sections can also be in a file that config.toml includes, or in a file in config.d. The tables merge key by key. A [[keybindings.command]] entry in a later file changes the earlier entry with the same name, or with the same key when one of them has no name. Add disabled = true to an entry to remove the earlier entry that it matches. The keybind manager and tuios keybinds unbind write a change to the file that sets the action. See Split the Config.

Modifier spellings

A key in config.toml can spell a modifier in more than one way. TUIOS reads each spelling as the same key.

The order of the modifiers does not matter, so shift+ctrl+x is the same key as 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 prints opt+f12 (tuios reads it as alt+f12). tuios keybinds doctor lists each key that TUIOS cannot read.

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 through the Kitty keyboard protocol. A super+ chord on F1 to F12, such as super+f12, works the same way. On a Mac keyboard, F12 can also be a media key, and then TUIOS does not get it.

Inspect and change bindings from the shell:

tuios keybinds list                       # the main tables
tuios keybinds browse                     # search every binding in an explorer
tuios keybinds doctor                     # conflicts, and keys taken from the pane
tuios keybinds explain alt+left           # everything one key does
tuios keybinds unbind close_window w      # take one key off one action
tuios keybinds free alt+left              # take a key off every action

doctor tags each finding with its evidence: certain comes from TUIOS routing, observed from the live pane, reference from a list of common program defaults. doctor and explain take --json and --guest <program>.

tuios keybinds browse opens the rows of tuios keybinds list --json in an explorer. Press / to search, and Tab or a click on a tab to show one scope. The detail pane shows the keys, the action, the scope and the description. q or Esc leaves it. Add a search to start with it: tuios keybinds browse spotlight. tuios keybinds list prints plain text, on a terminal too.

The keybind manager (Ctrl+B k) shows the same analysis in four tabs: Bindings, Conflicts, Guests and Record. Record captures the next key you press. On a binding, Ctrl+D removes it and Ctrl+X takes its key off every action.

Other keyboard layouts

Bindings work with layouts for non-Latin scripts, such as Cyrillic, Greek, Hebrew or Arabic. When no binding matches the character that a key types, TUIOS uses the key at the same position on a US layout. On a Ukrainian layout, the key that types ш is the US i key. So Ctrl+B then that key opens the Inbox.

• A binding on the typed character wins. You can still bind ш yourself.
• Text that you type into a pane, a rename or a search keeps the character that you typed.
• Ctrl on a non-Latin key sends the control code of the US key to the pane. Ctrl+с is Ctrl+C in the shell.

Latin layouts, such as AZERTY, QWERTZ or Dvorak, use the letters on their keys. A letter or a Ctrl chord means the key that it types, not the US key at its position. On Dvorak, Ctrl with the key that types b is Ctrl+B, the leader. The showkeys strip, the binding recorder and a tape show the chord the same way. tuios keybinds explain checks the key as you write it, so give it the Latin key.

This needs a terminal that sends the US-layout key through the Kitty keyboard protocol: Ghostty, kitty, WezTerm or foot. Other terminals send only the typed character. With those terminals, use a Latin layout for TUIOS commands.

Keys sent to a pane

In terminal mode, TUIOS sends these keys to the program in the pane:

• The keypad keys, with Num Lock on or off. Keypad Enter sends Enter.
• Begin, the center key of the keypad with Num Lock off.
• F13 and higher. A program that uses the legacy encoding gets them in the form that xterm sends.
• Insert, Delete, Page Up and Page Down with their modifiers. Ctrl+Delete stays Ctrl+Delete.

A program that uses the Kitty keyboard protocol gets each key with the number that the protocol gives it. Caps Lock, Num Lock and a modifier key pressed alone reach that program only when it asks for every key.

macOS

macOS treats Option as a compose key unless the terminal says otherwise. An Option chord then arrives as a character. TUIOS maps most of those characters back to the chord, which is why Option+1 to Option+9 work with no setup. Two kinds cannot be recovered:

• Dead keys. Option+e, i, n, u and ` send nothing until a second key. Alt+n (next window in terminal mode) takes two presses.
• Rewritten chords. Many terminals send Option+← and Option+→ as readline word motions, with no sign that an arrow was pressed.

To fix both, turn on your terminal's Option-as-Alt setting:

Ghostty also needs keybind = alt+left=unbind and keybind = alt+right=unbind, because its own keybinds rewrite those arrows first.

The prefix works on every terminal with no setup. Ctrl+B then an arrow, n, p, (, ), a or a digit covers every navigation command.

Command chords never reach a terminal program. macOS sends them to the menu bar.

Related