Keys by mode
Keys by mode: part of the Keybindings of TUIOS.
This page is one part of docs/KEYBINDINGS.md of the tuios repository. The Keybindings page lists every part.
Modes
Section: [keybindings.mode_control]. These keys work in window mode.
The default keys of this section are in Default keys: 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].
The default keys of this section are in Default keys: Window mode.
Section [keybindings.restore_minimized] restores one minimized window by position:
The default keys of this section are in Default keys: Window mode.
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.
The default keys of this section are in Default keys: Window mode.
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].
The default keys of this section are in Default keys: Window mode.
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.
BSP splits
Also in [keybindings.layout]. See BSP Tiling.
The default keys of this section are in Default keys: Window mode.
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.
Linux, others:
The default keys of this section are in Default keys: Terminal mode.
macOS:
The default keys of this section are in Default keys: Terminal mode.
Alt+Left and Alt+Right cost you word motions. Readline, fish and zsh use Alt+← and Alt+→ to move a word at a time. To give them back, run
tuios keybinds free alt+leftandtuios keybinds free alt+right. Ctrl+B then an arrow still moves focus.
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
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"]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.
Global keys
Section: [keybindings.global]. These keys work in window mode and terminal mode.
The default keys of this section are in Default keys: Global.
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].
The default keys of this section are in Default keys: Prefix (ctrl+b).
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.
Window prefix
Ctrl+B t, then the key. Section: [keybindings.window_prefix].
The default keys of this section are in Default keys: Window prefix (ctrl+b t).
Minimize prefix
Ctrl+B m, then the key. Section: [keybindings.minimize_prefix].
The default keys of this section are in Default keys: Minimize prefix (ctrl+b m).
Workspace prefix
Ctrl+B w, then the key. Section: [keybindings.workspace_prefix].
The default keys of this section are in Default keys: Workspace prefix (ctrl+b w).
Layout prefix
Ctrl+B L, then the key. Section: [keybindings.layout_prefix].
The default keys of this section are in Default keys: Layout prefix (ctrl+b L).
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.
The default keys of this section are in Default keys: Tape prefix (ctrl+b T).
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].
The default keys of this section are in Default keys: Debug prefix (ctrl+b D).
Session rail
Section: [keybindings.sidebar]. Active while the rail has the keyboard: press s in window mode, or Ctrl+B e.
The default keys of this section are in Default keys: Sidebar.
When the cursor is on a row in the files section, section [keybindings.sidebar_files] answers first:
The default keys of this section are in Default keys: Sidebar files.
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:
The default keys of this section are in Default keys: Sidebar agents.
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]:
The default keys of this section are in Default keys: 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]:
The default keys of this section are in Default keys: Inbox prompt.
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
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.
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 theme editor, the pickers, go-to, the navigator, the menus and the tape manager. The keys are the [keybindings.lists] section, and a list's footer names the keys that section binds.
The default keys of this section are in Default keys: Lists.
Set appearance.wrap_lists = false to stop at the ends instead of wrapping. The theme editor and the keybind manager keep a cursor for each tab, so a tab you come back to is on the row you left.
Every short text field, such as a filter, a search or the rename dialog, has a caret and takes the same keys as the agent answer fields:
The default keys of this section are in Default keys: Lists.
In a list's filter, Home and End move the list, and in the settings and help searches ← → keep their own meaning, so there the caret moves on the other keys. The agents view's answer fields also undo with Ctrl+Z, select with Shift and a move key, and wrap a long line.
List keys
The movement keys are in the [keybindings.lists] 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 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:
The default keys of this section are in Default keys: Lists.
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.
Leave copy mode, and other keys
- Enter leaves copy mode and gives the pane the keyboard back. From a selection it copies the selection first, as y does and as tmux's copy-mode-vi does. In the search prompt and after f or t, Enter still runs the search. The action is
copy_mode_exit. Setcopy_mode_exit = []in[keybindings.copy_mode]to give Enter its old meaning, which was nothing. - 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_upandterminal_focus_downalso 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.
Search in copy mode
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.
| Action | Palette entry | Does |
|---|---|---|
copy_mode_search_forward | Copy mode: search forward | Start copy mode and open the / prompt |
copy_mode_search_backward | Copy mode: search backward | Start copy mode and open the ? prompt |
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.
Mouse
| Gesture | Does |
|---|---|
| Click a pane | Focus it |
| Double-click a pane | In window mode, also start typing in it. appearance.click_to_type makes it a single click, or turns it off |
| Drag a title bar | Move the window. In tiling, drop it on the middle of a pane to swap the two. In BSP, drop it on the edge of a pane to split that pane. See Moving a window with the mouse |
| Alt + drag | Move the window from anywhere inside it (appearance.alt_drag) |
| Right-drag | Resize the window |
| Right-click | In window mode, open the menu for the pane, the dock or the desktop |
| Shift or Ctrl + right-click | Open the pane menu even when the program in the pane uses the mouse |
| Title bar buttons | Minimize, zoom or close |
| Click a dock item | Restore a minimized window |
| Wheel up | Enter copy mode and scroll, when the program is not using the mouse |
| Middle click | In terminal mode, paste from the clipboard. See Middle-click paste |
| Drag the right border | Scroll with the scrollbar |
| Hover a link | Show where it goes. The label shows the real target, also when the text on the screen is different |
| Ctrl + click a link | Open it. Shift+click also opens it, but most terminals keep it for their own selection. See Links |
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.
Menus over the rail, the Inbox and 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.
[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.
Keyboard layouts and macOS
Keyboard layouts and macOS: part of the Keybindings of TUIOS.
Default Keys
Every default key of TUIOS, by the part of the app it works in, written from the keymaps in the code.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.