Keybindings

Panes, panels and workspaces

Panes, panels and workspaces: part of the Keybindings of TUIOS.

This page is one part of docs/KEYBINDINGS.md of the tuios repository. The Keybindings page lists every part.

Editing sidebar files

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

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

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

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

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

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

Drag a file into a pane

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

KeyAction
J KMove half a page, one page of a PDF, or 5 percent of a film
Ctrl+D Ctrl+UMove half a page
Mouse wheel over the previewMove 3 lines, one page of a PDF, or 1 percent of a film
tShow the small frames of a film, or hide them
vShow the next view: the diff of a changed file, then the details
TabMove the keyboard inside the file
fFill the area of the panes, or go back

Inside the file, every key acts on the preview:

KeyAction
j kMove one line, one page of a PDF, or 1 second of a film
h lMove 1 second of a film, or one column of a table
vShow the next view: the diff of a changed file, then the details
tShow the small frames of a film, or hide them
d uMove half a page
g GGo to the start or the end, or the first or last page
/Search in a text. Lower case ignores case
n NGo to the next match, or the one before
:Go to a line number, or a page of a PDF
wWrap long lines, or cut them
[Start copy mode on the text
eOpen the file in your editor in a new pane, at the line at the top of the preview
fFill the area of the panes, or go back
Esc or TabMove the keyboard back to the list
SpaceClose the preview

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

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

Paths in a pane or the agents view

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

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

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

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

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

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

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

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

Modifier spellings

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

Writetuios reads it asWhere
opt+, option+, meta+alt+all platforms
cmd+, command+, win+super+all platforms
control+, ctl+ctrl+all platforms

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

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

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

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

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

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

Moving focus

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

DirectionWindow modeTerminal modeAfter the prefix key
Lefthalt+leftleft
Downjalt+downdown
Upkalt+upup
Rightlalt+rightright

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

Set appearance.focus_wrap = true to wrap focus at the edge of a tiled layout. Focus then goes to the window on the far side that faces the focused window. For example, left from the leftmost window goes to the rightmost window in the same rows. A window that fills the layout in that direction keeps focus. The option is off by default. See CONFIGURATION.md.

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

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

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

Finding a pane

Pane labels

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

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

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

[panes]
label_keys = "asdfghjkl"

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

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

The pane navigator

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

KeyWhat it does
j, k, arrowsMove
l, →Open a session or a workspace
h, ←Close it, or go to its parent row
spaceOpen or close
enterGo to the row: the session, the workspace and the pane
/Search
vChange the layout: tree, flat, cards
esc, qClose the navigator

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

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

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

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

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

[panes]
navigator_search = true

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

tuios list-windows --all --text 40 --json prints the same rows for a script. See CLI_REFERENCE.md.

New task

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

Go to anything

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

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

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

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

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

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

TermKeeps
kind:agent, kind:session, kind:workspace (or kind:ws), kind:paneRows of that kind
space:NAMERows of the sessions filed under that space
ws:NAgents, workspaces and panes on that workspace, by number or name

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

KeyWhat it does
The list keysMove. See Lists and panels
enterGo there: the session, then the workspace, then the pane
@, #, ! firstFilter to agents, sessions or workspaces. The picker's hint shows them as @ # ! filter
ctrl+uClear the query
escClose the picker
ctrl+rRename the session or workspace on the row. The picker stays open under the rename
ctrl+dDelete the session on the row, after a y. Never the session you are on

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

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

Neovim pane navigation

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

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

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

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

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

Lists and panels

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

KeysWhat it does
up, down, ctrl+p, ctrl+nMove one row. Up on the first row goes to the last, and down on the last to the first
home, endThe first or last row
pgup, pgdownA page up or down, stopping at the ends
k, j, g, GUp, down, first and last, in a list with no filter to type into
ctrl+uClear a typed filter (fixed)
alt+backspace, ctrl+w, ctrl+backspaceDelete the word before the caret in a typed filter (fixed). alt+backspace is Option+Backspace on a Mac whose terminal sends Option as Alt
wheelScroll the list under the pointer, stopping at the ends (fixed)

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

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

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

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

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

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

ActionDefault keys
list_upup, ctrl+p, k
list_downdown, ctrl+n, j
list_page_uppgup
list_page_downpgdown
list_firsthome, g
list_lastend, G

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

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

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

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

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

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

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

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

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

The rename dialog

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

KeysWhat it does
enterSave the name
escCancel
ctrl+uClear the field
alt+backspace, ctrl+w, ctrl+backspaceDelete the word before the caret
ctrl+cClear the field, or cancel when it is already empty

The field has a caret, and takes the caret and word keys every short field takes (see Lists and panels): home and end, alt+d and the others. A click on the clear hint in the dialog's border clears the field too. In the help's search, ctrl+u clears the query.

Mode keys in the dock

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

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

Messages

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

  • Put the pointer on a message to hold it. It does not go away while the pointer is on it. A key press, or the terminal losing focus, ends the hold. The hold ends after 60 seconds.
  • Put the pointer on a long message to see its first lines above the dock.
  • Click a long message to read all of it in the message view. A click on a pane's request to set the clipboard allows it.
  • Click a short message from a pane to go to that pane.
KeysWhereWhat it does
ctrl+b NanywhereShow the last message from a pane, or the last message that was too long for the dock, also after it went from the dock
ctrl+b janywhereGo to the pane of the newest message. On an agent integration notice, ask to install the integration
j, k, up, down, wheelmessage viewScroll one line
ctrl+d, ctrl+u, space, pgdown, pgupmessage viewScroll half a page
g, G, home, endmessage viewGo to the first or last line
ymessage viewCopy the message
entermessage viewGo to the pane the message came from
esc, qmessage viewClose the message view

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

Hints

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

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

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

Ctrl+click and drag still moves the pane. A link opens only when the pointer does not move. appearance.link_click sets which click opens a link. See CONFIGURATION.md for the settings, the opener and a table of terminals.

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

Moving a pane with the mouse

Drag a tiled pane by its title bar, or Ctrl+click anywhere in it and drag. In BSP tiling, dropping it on the middle of another pane swaps the two, and dropping it near an edge of another pane splits that pane and puts the dragged pane in the half toward that edge. While the button is down, the place the pane will land is highlighted. See LAYOUT_MODES.md.

Scratch terminal

Ctrl+B g shows the scratch terminal, a small layout of panes in a box over the current layout. Press it again to hide the box. The shells keep running between shows. Inside the box the window keys act on its panes: split, move the focus, resize, swap, zoom and close. The key works from inside the box. The action is toggle_scratch, and [scratch] sets the size of the box. See SESSIONS.md. To add more scratch terminals on keys of their own, see Command keys.

New worktree

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

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

Session note

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

The dock shows the note when you attach or switch to the session. See SESSIONS.md.

Picture in picture

p in window mode pins the focused pane as the picture-in-picture view, a small live copy of the pane in a corner of the screen. Press p again, on any pane, to unpin it. A click on the view focuses the pane. The action is toggle_pip, and [pip] sets the size and the corner. See SESSIONS.md.

Rail pane

P in window mode gives the keyboard to the pane in the rail's pane section. alt+esc gives it back. The action is focus_rail_pane. See CONFIGURATION.md.

Spotlight

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

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

WhereTurn off the spotlight
Window modeEsc
Terminal modeCtrl+B B
Any modeClick the Spotlight chip in the dock

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

Pick a path

Alt+; in terminal mode opens the path picker at the cursor of the focused pane. Ctrl+B . opens it too. The picker lists the folder that the shell in the pane is in. Folders come first, then files. Type to filter the names. Press Enter to type the path of the selected name at the cursor. tuios quotes the path for the shell in the pane, by the same rules as a drag from the sidebar. See Drag a file into a pane.

KeyWhat it does
TextFilter the names
Up, Down, Ctrl+P, Ctrl+NMove the selection
TabOpen the selected folder. On a file, complete the name
Shift+Tab, Backspace with no filter textGo up one folder
/ at the startStart an absolute path
~/ at the startStart a path in the home folder
EnterType the path and close the picker
Alt+HShow or hide the hidden files
EscClose the picker and type nothing

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

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

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

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

Calm mode

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

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

The dock shows calm while it is on. calm 3 means that 3 messages are in the log. When you turn calm mode off, tuios tells you how many messages came in. The action is toggle_calm. To keep calm mode on after a restart, set appearance.calm = true. See CONFIGURATION.md.

Paste an image

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

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

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

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

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

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

SystemTool
Linux, Waylandwl-paste from wl-clipboard
Linux, X11xclip. xsel cannot read an image.
macOSosascript, or pngpaste when it is installed
WindowsPowerShell
WSLpowershell.exe, which reads the Windows clipboard. WSLg's wl-paste and xclip see no image copied on Windows.

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

A pane on another machine

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

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

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

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

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

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

tuios does not read the clipboard in these cases:

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

Command keys

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

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

The command gets these variables:

VariableValue
TUIOS_SESSIONThe session in which you pressed the key
TUIOS_SOCKETThe socket of the daemon
TUIOS_ACTIVE_PANE_IDThe pane that had the focus
TUIOS_ACTIVE_PANE_CWDThe folder in which the command starts

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

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

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

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

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

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

Recipes

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

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

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

Your actions

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

FieldRuns
action = "new_window"A built-in action, as its key does
run = ["code", "{pane.cwd}"] with inA program and its arguments, in a popup (the default), a pane, a scratch pane, or silently
plugin = "id.action"A plugin action
[[actions]]
name = "open-in-editor"
label = "Open the folder in the editor"
key = "prefix+alt+e"
run = ["code", "{pane.cwd}"]
in = "silent"

key is written as a command key: prefix+ puts it after the leader, and any other key acts in window and terminal mode. You can also bind user:NAME in any [keybindings.*] table.

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

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

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

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

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

tuios actions list lists your actions, tuios actions list NAME shows one (and why tuios ignores it, when it does), and tuios actions run NAME --dry-run prints the arguments it would run, with the placeholders filled (CLI_REFERENCE.md). A mistake in an entry is a warning, and tuios ignores that entry.

Your menus

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

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

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

[menus.tools]
title = "Tools"
items = ["user:deploy", "---", "new_window"]
KeyDoes
addPuts the rows after the row whose action is after, or at the end
removeRemoves the rows with these actions
itemsReplaces all the rows (the rows of any other menu)
titleHeads a menu that is not a target's
stickyKeeps the which-key panel open after a key runs

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

Row keyIs
action or menuWhat the row runs: an action, or the menu NAME (open_menu:NAME)
keyThe key in the which-key panel, or a list of keys
labelThe row's text, in the place of the action's
whenShows the row only while the focused pane matches (see below)

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

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

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

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

Master-stack layout

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

KeysActionWhat it does
Ctrl+B L ocycle_master_positionMove the master panes to the next side: left, right, top, bottom, center
Ctrl+B L Enterswap_with_masterSwap the focused pane with the master pane
Ctrl+B L mfocus_masterFocus the master pane
Ctrl+B L iadd_masterMake one more pane a master pane
Ctrl+B L dremove_masterMake one pane fewer a master pane
Ctrl+B =, or = in window modeequalize_splits, equalize_splitsGive the master panes and the stack their default sizes again

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

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

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

See LAYOUT_MODES.md.

Ask before a pane closes

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

[appearance]
confirm_close = "busy"   # never (default), busy or always
  • never closes at once. This is the default.
  • busy asks when the pane runs something besides its shell, such as an agent, an editor or a long job. A pane at its shell prompt closes at once.
  • always asks for every pane.

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

Focus only

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

Close every pane on a workspace

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

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

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

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

When the closed workspace is not on screen, or when tuios goes back from it, the workspaces above it move down one, so the numbers follow the positions. See CONFIGURATION.md.

tuios close-workspace does the same from a shell. See CLI_REFERENCE.md.

Restart the daemon

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

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

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

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

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

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

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

tuios restart-server does the same from a shell. See CLI_REFERENCE.md.

Move a pane to another workspace

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

ActionmacOSLinux and otherWhat it does
switch_workspace_1 to switch_workspace_9opt+Nalt+NShows workspace N.
move_and_follow_1 to move_and_follow_9opt+shift+Nalt+shift+NSends the focused pane to workspace N and shows workspace N.
send_to_workspace_1 to send_to_workspace_9ctrl+opt+Nctrl+alt+NSends the focused pane to workspace N and stays on this workspace. Focus goes to another pane here.

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

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

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

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

Cycle through workspaces

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

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

Cycle through machines

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

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

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

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

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

Actions for a tmux-style keymap

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

ActionWhat it does
mark_paneMarks the focused pane, or clears the mark when it is the marked one. The marked pane shows [marked] in its title bar.
join_marked_left, join_marked_right, join_marked_up, join_marked_downMoves the marked pane next to the focused one, on that side, from this workspace or another. Needs BSP tiling.
resize_pane_left_5, resize_pane_right_5, resize_pane_up_5, resize_pane_down_5Moves the focused pane's edge by 5 cells. The _20 actions move it by 20. Under the leader, the key repeats without a second leader press, as tmux bind -r does.
new_workspaceGoes to the first workspace with no pane, the one the dock's + button opens, and opens a pane there. On an empty workspace past the last one in use, that workspace is the new one: it stays there and opens the pane there.
last_workspaceGoes back to the workspace you were on before this one, as tmux last-window does. Press it again to go back and forth.
break_paneMoves the focused pane to the first workspace with no pane and goes with it, as tmux break-pane does.
last_sessionGoes back to the session you were on before this one, as tmux switch-client -l does.
send_prefixSends the leader key to the program in the focused pane, as pressing the leader two times in terminal mode does. Use it for screen's C-a a, or for a tmux in the pane.
move_workspace_left, move_workspace_rightSwaps this workspace with the one before or after it, and follows it. The two workspaces trade numbers, so the moved one answers to its new number.
cycle_layoutCycles BSP, master-stack and scrolling.
reload_configReads config.toml again, as the "Reload config" palette row does.
toggle_mouseStops asking the terminal for mouse reports, so the terminal selects text itself. Run it again to turn the mouse back on. The setting lasts until you quit.

For tmux's synchronize-panes, bind toggle_multifocus_all. It puts every pane on the workspace in the multifocus set, so typing goes to all of them. See LAYOUT_MODES.md.

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

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

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

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

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

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

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

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.

Split into the same ssh

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

ActionWhat it does
split_ssh_horizontalSplits the pane top and bottom.
split_ssh_verticalSplits the pane left and right.
new_window_sshOpens a new window.

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

When the focused pane does not run ssh, the action opens an ordinary pane. You can use the keys in every pane. Some ssh lines also get an ordinary pane. See CONFIGURATION.md.

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

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.

On this page