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.
Esccancels 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 orShift+click on a row copies its path.
After the drop, the pane has the focus and the mode does not change.
tuios quotes the path for the program in the pane. It knows sh, bash, rbash,
zsh, dash, ksh, ksh93, mksh, lksh, oksh, loksh, pdksh, posh, yash, ash, hush,
fish, nu, csh, PowerShell, elvish and cmd. Other programs get POSIX single
quotes, except a name with a backslash before a quote or another backslash, or
ending in a backslash, which gets its quotes and backslashes written outside
the single quotes, so fish behind tmux or script reads it as a POSIX shell
does. A folder path ends in /. A space follows the path, so you can
type the next word. Hold Alt when you release a folder to type a cd to it.
The path goes in as a paste. A program that turned on bracketed paste gets it
as one paste.
tuios does not paste the path in these cases. The label and a dock note say why.
- The pane is on another machine.
- The pane runs ssh or mosh, or its shell reports a folder on another machine.
- The file is in a listing from another machine.
- The name holds a line break or a control character.
- The pane is in copy mode.
A drag never copies or moves the file. To turn the drag off, set
appearance.sidebar.file_drag = false.
When the session runs on another machine, tuios does not check the file on your machine. If the editor is not on that machine, no pane opens. tuios shows a dock note that names the editor and the machine, so you know what to check.
With the File editor setting empty, a remote session uses $EDITOR from this
machine. Set the File editor if the far machine has a different editor.
tuios can not edit a file that lists from a different machine than the one the session runs on.
Shift+Enter needs a terminal that reports modified Enter, such as one that
uses the Kitty keyboard protocol. On other terminals, use the Edit row in the
context menu of a file, or bind file_edit to a different key.
S sends the selected file or folder to a host. tuios asks which host, then
which folder. The folder field starts as ~/Downloads/tuios/.
tuios makes the folder when it is not there. A file that is there stays, and
the copy gets the name name (from HOST).ext. The context menu of a row has a
Send to host row that does the same. The binding is file_send in
[keybindings.sidebar_files].
Space shows a quick look preview of the selected row. The preview opens over
the panes and shows:
- code with syntax colours and line numbers,
- Markdown as formatted text,
- a picture, a page of a PDF or a film frame,
- the names in a folder.
A file that is not text shows its type and size. A long text opens at once, and
tuios reads more of it as you move. Line numbers after a jump to the end are
estimates, and the preview says so. A search or a count stops after 5 seconds
and says how far it went. Press n to go on.
A PDF shows one page and a bar with the page number. Click the bar to go to a page. At 16 colours the preview shows the words of the page.
A film shows one frame and a bar with the time. Click or drag the bar to move to a
time. There is no playback. Press t to show 7 small frames from across the film.
At 16 colours the preview shows the facts of the film.
Markdown shows HTML as formatted text, with alerts, footnotes and reference links.
An image alone on its line shows as a picture when the terminal can draw one. A
table keeps every cell: a long cell wraps in its column. A table with too many
columns shows each row as a list of names and values. A <picture> shows the
source for a dark or a light theme, as the theme is. Quick look reads no address
on the web: an image there, a WebP, an SVG and an AVIF show as one line of their words.
A <details> block starts closed, and Enter inside the file opens it. A Mermaid
block shows as a diagram in text.
JSON is laid out for reading. CSV and TSV show as a table. An archive shows the
files in it. A binary file shows its first 16 KiB in hex. J and K step through
the frames of a GIF.
Up and Down (or j and k) move the cursor to the next row, and the preview
shows that row. Space or Esc closes the preview. A click outside it closes
it too. When the sidebar loses keyboard focus, the preview closes.
The mouse over the preview stays in the preview. A pane under it does not get the focus or the mouse. Drag over the text or the Markdown to select it. A double click selects a word, and a triple click selects a line. The selection goes to the clipboard when you release the button. The next click or key removes the selection.
These keys move inside the file. The preview shows the keys that work now. All other keys go to the sidebar.
| Key | Action |
|---|---|
J K | Move half a page, one page of a PDF, or 5 percent of a film |
Ctrl+D Ctrl+U | Move half a page |
| Mouse wheel over the preview | Move 3 lines, one page of a PDF, or 1 percent of a film |
t | Show the small frames of a film, or hide them |
v | Show the next view: the diff of a changed file, then the details |
Tab | Move the keyboard inside the file |
f | Fill the area of the panes, or go back |
Inside the file, every key acts on the preview:
| Key | Action |
|---|---|
j k | Move one line, one page of a PDF, or 1 second of a film |
h l | Move 1 second of a film, or one column of a table |
v | Show the next view: the diff of a changed file, then the details |
t | Show the small frames of a film, or hide them |
d u | Move half a page |
g G | Go to the start or the end, or the first or last page |
/ | Search in a text. Lower case ignores case |
n N | Go to the next match, or the one before |
: | Go to a line number, or a page of a PDF |
w | Wrap long lines, or cut them |
[ | Start copy mode on the text |
e | Open the file in your editor in a new pane, at the line at the top of the preview |
f | Fill the area of the panes, or go back |
Esc or Tab | Move the keyboard back to the list |
Space | Close the preview |
Change these keys in [keybindings.quick_look] and
[keybindings.quick_look_inside].
[ in a text file starts copy mode 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.
| Write | tuios reads it as | Where |
|---|---|---|
opt+, option+, meta+ | alt+ | all platforms |
cmd+, command+, win+ | super+ | all platforms |
control+, ctl+ | ctrl+ | all platforms |
meta is Alt, as it is to tmux, emacs and readline. A kitty keyboard Meta key is a different key, and no spelling names it.
The order of the modifiers does not matter, so shift+ctrl+x is ctrl+shift+x. This applies to leader_key, to every binding table, and to tuios keybinds explain, free and unbind. tuios keybinds explain opt+f12 shows opt+f12 (tuios reads it as alt+f12). tuios keybinds doctor lists each key that tuios cannot read.
In [keybindings.terminal_mode], middle names a press of the middle mouse
button. It accepts ctrl, alt and shift, such as ctrl+middle. Other
tables do not accept it. A program that uses the mouse, such as vim with
mouse=a, lazygit or tmux, gets a plain middle press. A binding with a
modifier runs over such a program too. Other mouse gestures are fixed.
You can use one config.toml on macOS and on Linux. On Linux, opt+1 is alt+1. tuios keybinds doctor lists these keys for information.
tuios ignores a key that it cannot read, such as ctrl+nope, and loads the rest of the file. The action gets its default key when it has no other key. If another action already has that default key, the action has no key. A leader that tuios cannot read changes to ctrl+b. tuios shows a config problem when it starts. The log viewer (leader D l) names each key and its file. tuios keybinds doctor shows the same information. A table name that tuios does not have, such as [keybindings.terminal], is reported the same way, with the table you most likely meant.
A super+ chord needs a terminal that sends the Super key. Most macOS terminals keep Command chords for their own menus. Ghostty and kitty send an unbound Command chord under the Kitty keyboard protocol.
Moving focus
Four keys move focus to the window in a direction. Each key has a binding in window mode, in terminal mode, and after the prefix.
| Direction | Window mode | Terminal mode | After the prefix key |
|---|---|---|---|
| Left | h | alt+left | left |
| Down | j | alt+down | down |
| Up | k | alt+up | up |
| Right | l | alt+right | right |
Focus goes to the nearest window that lies in that direction and faces the focused window. At the edge of a tiled layout, focus stays where it is. With tiling off, a window that does not face the focused window can also get focus.
Set appearance.focus_wrap = true to wrap focus at the edge of a tiled layout. Focus then goes to the window on the far side that faces the focused window. For example, left from the leftmost window goes to the rightmost window in the same rows. A window that fills the layout in that direction keeps focus. The option is off by default. See CONFIGURATION.md.
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.
| Key | What it does |
|---|---|
j, k, arrows | Move |
l, → | Open a session or a workspace |
h, ← | Close it, or go to its parent row |
space | Open or close |
enter | Go to the row: the session, the workspace and the pane |
/ | Search |
v | Change the layout: tree, flat, cards |
esc, q | Close the navigator |
The navigator has three boxes. Search is at the top and shows how many panes
match, as 3/7. Panes is the list. Preview shows the screen of the pane under
the cursor, in the colors of that pane.
The list has three layouts. Tree shows the sessions, their workspaces and their
panes. Flat shows one row for each pane, with its session and workspace. Cards
shows two rows for each pane: the name and the command, then the session, the
workspace and the folder. v changes the layout. Your client keeps the last
layout until it closes. [panes] navigator_layout sets the first layout. See
CONFIGURATION.md.
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 = trueThe 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/paymentsA pane of the session you are attached to ends with its working directory, with your home folder as ~. On a narrow screen the folder is cut in the middle, and it is left out before the name gives way. current stays last.
With nothing typed, the first row is the place you were on last, so Ctrl+B G and enter take you back to where you were. The agents that need you come right after it, the one waiting longest first, then the other places you were on recently, the most recent first, then every agent, session and workspace. Panes are listed once you type something. A session has many panes, and the ones you were just on are already in the recent places.
Typed words are a fuzzy search over the names a row shows: the session, the workspace, the pane and its folder, and for an agent its harness and its last message. A key:value term narrows the rows instead, and every term has to match. The terms are the selector the agents view takes (harness:, state:, needs:you, session:, group:, host:, name:), and three more:
| Term | Keeps |
|---|---|
kind:agent, kind:session, kind:workspace (or kind:ws), kind:pane | Rows of that kind |
space:NAME | Rows of the sessions filed under that space |
ws:N | Agents, workspaces and panes on that workspace, by number or name |
A value is a glob, and commas between values mean any of them, as in kind:session,workspace. A term that does not fit a row leaves it out: harness: keeps only agents, and ws: leaves out the sessions. @, # or ! at the start of the query is kind:agent, kind:session or kind:workspace. For example, #space:surge lists the sessions in the surge space, and @needs:you lists the agents that need you.
| Key | What it does |
|---|---|
| The list keys | Move. See Lists and panels |
enter | Go there: the session, then the workspace, then the pane |
@, #, ! first | Filter to agents, sessions or workspaces. The picker's hint shows them as @ # ! filter |
ctrl+u | Clear the query |
esc | Close the picker |
ctrl+r | Rename the session or workspace on the row. The picker stays open under the rename |
ctrl+d | Delete the session on the row, after a y. Never the session you are on |
The keys that opened the old lists open this picker with the filter typed: Ctrl+B S on # (the sessions), Ctrl+B W on ! session:NAME (this session's workspaces), and the palette's "All windows" on kind:pane session:NAME (this session's panes). With # NAME typed and no session called NAME, enter makes that session.
Workspaces and panes are listed for the sessions on the machine you are attached to. A session on another machine is listed, and its agents are, and enter on it attaches that machine as the rail does. A workspace of a session you are not attached to shows its number, because its name is not sent to your client.
Neovim pane navigation
The optional tuios-nvim-navigator
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.
| Keys | What it does |
|---|---|
up, down, ctrl+p, ctrl+n | Move one row. Up on the first row goes to the last, and down on the last to the first |
home, end | The first or last row |
pgup, pgdown | A page up or down, stopping at the ends |
k, j, g, G | Up, down, first and last, in a list with no filter to type into |
ctrl+u | Clear a typed filter (fixed) |
alt+backspace, ctrl+w, ctrl+backspace | Delete the word before the caret in a typed filter (fixed). alt+backspace is Option+Backspace on a Mac whose terminal sends Option as Alt |
| wheel | Scroll the list under the pointer, stopping at the ends (fixed) |
The theme editor and the keybind manager keep a cursor for each of their tabs. Go to another tab and back, and the cursor is on the row you left. A filter that changes puts its list back on the first row.
A footer names the move keys as [keybindings.lists] binds them: ↑↓ while
the arrows come first (up/down with ASCII glyphs), and otherwise the first up
and the first down key, such as ctrl+k/ctrl+j. A motion with no key leaves
its hint out.
The word keys take a word the way the shell's Option+Backspace does: they skip
the characters at the end that are not part of a word, then take the word. A word
is letters, digits and _, and a blank, /, . or - ends one. So
src/dir1/dir2 becomes src/dir1/, then src/, then nothing. Every short text
field in tuios takes them, the rename, file and new worktree dialogs among them.
Every short text field also has a caret. left and right move it a
character; alt+left, ctrl+left and alt+b, and alt+right, ctrl+right
and alt+f, a word; home and ctrl+a, and end and ctrl+e, to the start
and the end. alt+d, alt+delete and ctrl+delete delete the word after the
caret, ctrl+k cuts from the caret to the end, ctrl+u clears the field, and
typed or pasted text goes in at the caret. In a list's filter, and in the help
and settings searches, left and right keep their own meaning (the section,
the tab or the row's value), and home and end move the list, so there the
caret moves with the other keys.
The agents view's one-line fields (the selector line, the reason for a reject
and the answer to a prompt) take these keys too, and have more: ctrl+z
undoes, shift with a move key selects, and a long line wraps in place of
scrolling sideways.
The movement keys are the [keybindings.lists] section. Every list in tuios
moves on them: the pickers and dialogs, the review panel, the scrollback
browser's command list, the composer's paste pager, the spawn sheet, and the
explorers behind tuios keybinds browse, tuios config browse and
tuios help -i. The agents view's compare answers with J (judge) and K
(keep), moves between attempts with left and right, and scrolls with j and
k; only its page keys come from this section. Each action takes the keys that do it:
| Action | Default keys |
|---|---|
list_up | up, ctrl+p, k |
list_down | down, ctrl+n, j |
list_page_up | pgup |
list_page_down | pgdown |
list_first | home, g |
list_last | end, G |
A key that is a single printable character is a letter key. Only a list with no
filter to type into reads it, because a list with a filter keeps its letters
for the filter. To move on ctrl+j and ctrl+k as well as the arrows:
[keybindings.lists]
list_down = ["down", "ctrl+j"]
list_up = ["up", "ctrl+k"]An action you name replaces its default keys, so the example above gives
ctrl+n, ctrl+p, j and k back to the pane or the filter. An action you
leave out keeps its defaults, and list_page_down = [] unbinds it.
Set appearance.wrap_lists = false to stop at the ends instead of wrapping.
The close-session and file confirmations never wrap, so up from Cancel cannot
land on the answer that deletes.
With nothing typed, the command palette lists its commands under category headers. The headers are not rows: the cursor steps over them. Once you type, the commands are ranked by how well they match, and each row names its category in a quiet column on the right.
Type # to search actions instead of commands. #close lists every action
with "close" in its name, key or description, with the keys it is on today.
Press Enter to run the action. The palette closes first, so the action works
on the pane and the mode underneath, as its key would. Press ctrl+e to open
the keybind manager on the action, to rebind or unbind it. The footer shows
that key while a # search is open.
Some actions work only in their own view, such as a rail, Inbox, mail or copy
mode key. The palette has nothing for them to act on, so Enter on one opens
the keybind manager, as ctrl+e does.
The prefix menu (which-key) shows the keys after the leader in sections
(Windows, Panes, Sessions, Modes, Menus, Tools, and Agents once an agent has
run), laid out in as many columns as the screen holds. A key marked with +
opens a further menu. On a screen too narrow for every column, the
descriptions are cut before any key is left out.
The key hints at the foot of a panel stay on one row. When they do not fit,
they shorten in steps. First, ctrl+ becomes ^, alt+ becomes M- and
shift+ becomes S-. Then the least important hints go, one whole hint at a
time. The way out, such as esc, stays. Only when the most important hints
still do not fit do their labels go, from the last hint back. A hint is never
cut in the middle of a word.
The rename dialog
One dialog renames a window, a session and a workspace. It opens holding the current name. Its keys are fixed.
| Keys | What it does |
|---|---|
enter | Save the name |
esc | Cancel |
ctrl+u | Clear the field |
alt+backspace, ctrl+w, ctrl+backspace | Delete the word before the caret |
ctrl+c | Clear the field, or cancel when it is already empty |
The field has a caret, and takes the caret and word keys every short field
takes (see Lists and panels): home and end, alt+d
and the others. A click on the clear hint in the dialog's border clears the
field too. In the help's search, ctrl+u clears the query.
Mode keys in the dock
Copy mode, multi copy mode and hints mode show their keys at the right end of
the dock while the mode is open. The keys follow the rule for panel footers
above, so a narrow screen shows fewer keys and never part of one. The main
action and the way out of the mode always show. In hints mode, ? shows all of
its keys in the help. A message that arrives while a mode is open shows in the
place of the keys until the message goes. The dock component for the keys is
copy-help.
An empty list says why it is empty in the middle of the panel, with the one key worth pressing next under it. A list that is still loading draws nothing for its first half second, so a fast load never flashes a "reading" line.
Messages
A message shows at the right end of the dock. A message that is too long
for the dock stops after its last whole word, with … and more. A word with
no space in it, such as a long path, is cut where the room ends.
- Put the pointer on a message to hold it. It does not go away while the pointer is on it. A key press, or the terminal losing focus, ends the hold. The hold ends after 60 seconds.
- Put the pointer on a long message to see its first lines above the dock.
- Click a long message to read all of it in the message view. A click on a pane's request to set the clipboard allows it.
- Click a short message from a pane to go to that pane.
| Keys | Where | What it does |
|---|---|---|
ctrl+b N | anywhere | Show the last message from a pane, or the last message that was too long for the dock, also after it went from the dock |
ctrl+b j | anywhere | Go to the pane of the newest message. On an agent integration notice, ask to install the integration |
j, k, up, down, wheel | message view | Scroll one line |
ctrl+d, ctrl+u, space, pgdown, pgup | message view | Scroll half a page |
g, G, home, end | message view | Go to the first or last line |
y | message view | Copy the message |
enter | message view | Go to the pane the message came from |
esc, q | message view | Close the message view |
The log viewer (ctrl+b D l) lists every message the dock showed, and every
warning and error. The entry under the cursor shows wrapped under the list.
Press enter, or click an entry, to read it in the message view. E copies
the errors and A copies the whole log.
Hints
Ctrl+B F puts a short label on each URL, path, hash, address and number in
the focused pane. Type a label to copy the text. Type it with Shift to copy
the text and type it into the pane. Type it with Ctrl to open a URL or a
path. ? shows all of the keys of hints mode. esc closes. The dock shows
the keys while the labels show. See HINTS.md for the patterns and the
[hints] settings. The action is hints, so you can bind it to a different
key.
The hints_all_panes action puts labels on all panes that the workspace
shows. The focused pane gets the shortest labels. Shift and a label types
the text into the focused pane. This action has no default key. Bind it, or
run it from the command palette. Set hints.all_panes = true to make
Ctrl+B F do the same.
Links
Ctrl+click on a link opens it. Shift+click also opens it, but most
terminals keep Shift+click for their own selection. Hover a link to see
where it goes. The label under the pointer shows the real target, also when
the text on the screen is different.
Ctrl+click and drag still moves the pane. A link opens only when the
pointer does not move. appearance.link_click sets which click opens a
link. See CONFIGURATION.md 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:
| Where | Turn off the spotlight |
|---|---|
| Window mode | Esc |
| Terminal mode | Ctrl+B B |
| Any mode | Click the Spotlight chip in the dock |
In terminal mode Esc goes to the program in the pane, so vim and other
programs get it. An open dialog, menu or popup closes before Esc turns the
spotlight off. The actions are toggle_spotlight and
toggle_spotlight, and [spotlight] sets the size and the dimming.
The key was b in earlier versions.
Pick a path
Alt+; in terminal mode opens the path picker at the cursor of the focused
pane. Ctrl+B . opens it too. The picker lists the folder that the shell in
the pane is in. Folders come first, then files. Type to filter the names.
Press Enter to type the path of the selected name at the cursor.
tuios quotes the path for the shell in the pane, by the same rules as a drag
from the sidebar. See Drag a file into a pane.
| Key | What it does |
|---|---|
| Text | Filter the names |
Up, Down, Ctrl+P, Ctrl+N | Move the selection |
Tab | Open the selected folder. On a file, complete the name |
Shift+Tab, Backspace with no filter text | Go up one folder |
/ at the start | Start an absolute path |
~/ at the start | Start a path in the home folder |
Enter | Type the path and close the picker |
Alt+H | Show or hide the hidden files |
Esc | Close the picker and type nothing |
The filter line shows the path that you built, for example src/app/. A
click on a name types its path. The mouse wheel moves the selection.
The path is relative to the folder of the pane. A path that starts with /
or ~/ stays absolute. tuios puts a path with a space or a special character
in quotes. When the program in the pane turned on bracketed paste, tuios
sends the path as a paste. Else it types the path.
The picker works in a pane on another machine. The daemon on that machine lists the folder, with the same read rules as the sidebar's files section. When the shell in the pane runs ssh to another machine, the picker does not open.
The action is pick_path. path_picker.show_hidden = true shows the hidden
files when the picker opens. The default is false.
Calm mode
Ctrl+B Z turns calm mode on and off. Use it to keep your attention on one
task. While calm mode is on:
- Nothing moves. Window slides, panel fades, the working-agent shimmer and the
copy sweep stop. Your
appearance.motionlevel 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:
| System | Tool |
|---|---|
| Linux, Wayland | wl-paste from wl-clipboard |
| Linux, X11 | xclip. xsel cannot read an image. |
| macOS | osascript, or pngpaste when it is installed |
| Windows | PowerShell |
| WSL | powershell.exe, which reads the Windows clipboard. WSLg's wl-paste and xclip see no image copied on Windows. |
The file is a PNG, JPEG, GIF, WebP, BMP or TIFF image of 8 MB or less. Only
you can read it. tuios deletes it after one hour, or when the daemon stops.
The file is in the paste folder next to the tuios socket. The folder keeps
at most 50 images and 100 MB. When it is full, tuios deletes the oldest image.
If the paste folder is a symbolic link, tuios does not paste.
A pane on another machine
A pane can run on another machine in three ways. In each, tuios writes the image on that machine:
- A session on a host, attached with
tuios attach --host NAME. The daemon on the host writes the file. - A window on a host in a session of this machine. The daemon on the host writes the file.
- A pane of this machine that runs
sshormoshto another machine, such asssh buildorssh -t build tmux. tuios reads the ssh command line from the process. It resolves that line and each[hosts]entry withssh -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 withtuios 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
-For-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 -Xforwards 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%"keyis the key that runs the command. A key that starts withprefix+works after the leader (Ctrl+B). Any other key works in window mode and in terminal mode.typeis one of these:scratch: a scratch terminal of its own. The key shows it and hides it, asCtrl+B gdoes 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 nocommand, 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 exampleexample.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.
commandruns withsh -c, so you can write pipes and quotes. It starts in the folder of the focused pane.descriptionis the name in the command palette and intuios keybinds list. It is optional.namekeeps 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, andtuios keybinds doctorshows it. Give one of the two entries aname.widthandheightset the size of a scratch or popup entry, in cells (100) or percent (80%). The default is80%.
The command gets these variables:
| Variable | Value |
|---|---|
TUIOS_SESSION | The session in which you pressed the key |
TUIOS_SOCKET | The socket of the daemon |
TUIOS_ACTIVE_PANE_ID | The pane that had the focus |
TUIOS_ACTIVE_PANE_CWD | The folder in which the command starts |
A command key never takes a key from a tuios action or from the leader key.
When the key is taken, tuios keybinds doctor shows the entry as dead. When
two entries have the same key, the first entry in config.toml runs, and the
doctor shows the other as dead. To move an entry to a different key, edit its
key in config.toml. The command palette lists each entry, and
tuios keybinds list shows them under Commands.
A key with no modifier and no prefix+, for example g, works in terminal
mode too. It takes that letter from every pane, so tuios shows a warning. Use
prefix+g or a key with a modifier, for example alt+g.
When a scratch command stops in its first moments, for example because the program is not installed, the dock shows its exit code. The next press starts it again. tuios does not start it again by itself.
The command and the palette row of an entry change when you save
config.toml. A changed key works at the next key press, as for the other
keybindings. When you remove or rename an entry, or change the description of
an entry that has no name, the panes of its scratch terminal close at the
next reload. The
dock shows a message.
In a session on a different machine, a scratch, popup or pane entry runs
on the machine of the session. The command runs as the user of that machine,
in the folder of the focused pane on that machine. A ~ in the command is the
home folder on that machine. A popup or scratch entry there needs "open"
in the allow list of that machine's [hosts] table for your machine. Without
it, the dock shows a message that names the table to change. A shell entry
runs on the machine that runs the tuios client.
Only a key press or the command palette runs a command key. A change to
config.toml does not run a command. A pane that has the respond grant can
press keys as you through run-command. It can press a command key, also from
a session on a different machine, and a shell entry then runs on this
machine. Give the respond grant only to a pane that you trust.
Recipes
These are command keys for common tasks. Copy an entry into config.toml and
change the key to taste. Run tuios keybinds doctor after you add one, to
check the key is free.
Per-session notes. This scratch entry opens $EDITOR on a notes file
named after the session, and makes the notes folder first. It falls back to
vi when $EDITOR is not set.
[[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:
| Field | Runs |
|---|---|
action = "new_window" | A built-in action, as its key does |
run = ["code", "{pane.cwd}"] with in | A program and its arguments, in a popup (the default), a pane, a scratch pane, or 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"]| Key | Does |
|---|---|
add | Puts the rows after the row whose action is after, or at the end |
remove | Removes the rows with these actions |
items | Replaces all the rows (the rows of any other menu) |
title | Heads a menu that is not a target's |
sticky | Keeps the which-key panel open after a key runs |
A row is an action name, "---" for a separator, or a table:
| Row key | Is |
|---|---|
action or menu | What the row runs: an action, or the menu NAME (open_menu:NAME) |
key | The key in the which-key panel, or a list of keys |
label | The row's text, in the place of the action's |
when | Shows the row only while the focused pane matches (see below) |
A submenu row acts on the target of the first menu. A shipped action keeps its label and its state (a dimmed row stays dimmed). Another built-in action shows its description. A key on a target's row is not read: a target's menu opens on its target.
A user:NAME row shows only on the targets in the action's targets (a pane
when it has none), and only while its when matches the focused pane:
[[actions]]
name = "explain-error"
targets = ["pane", "selection"]
when = { agent_state = ["idle", "done"], program = "claude" }
action = "copy_selection"when reads agent_state, harness, program, host and has_selection
("true" or "false"). Each value is a string or a list of strings, and the
fact must equal one of them. A row's own when works the same way, in a
right-click menu. The which-key panel shows every row that has a key.
Master-stack layout
The layout prefix (Ctrl+B L) has keys for the master-stack layout. They act
on the workspace on screen.
| Keys | Action | What it does |
|---|---|---|
Ctrl+B L o | cycle_master_position | Move the master panes to the next side: left, right, top, bottom, center |
Ctrl+B L Enter | swap_with_master | Swap the focused pane with the master pane |
Ctrl+B L m | focus_master | Focus the master pane |
Ctrl+B L i | add_master | Make one more pane a master pane |
Ctrl+B L d | remove_master | Make one pane fewer a master pane |
Ctrl+B =, or = in window mode | equalize_splits, equalize_splits | Give the master panes and the stack their default sizes again |
The resize keys move the divider between the master panes and the stack. With
the master on the left, the right or in the center, the width keys move it,
such as < and > in window mode. With the master at the top or the bottom,
the height keys move it. The workspace keeps the new size.
set_master_position_left, set_master_position_right,
set_master_position_top, set_master_position_bottom and
set_master_position_center have no default key. To bind one, add it to a
section:
[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 alwaysnevercloses at once. This is the default.busyasks 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.alwaysasks 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
escto 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.
| Action | macOS | Linux and other | What it does |
|---|---|---|---|
switch_workspace_1 to switch_workspace_9 | opt+N | alt+N | Shows workspace N. |
move_and_follow_1 to move_and_follow_9 | opt+shift+N | alt+shift+N | Sends the focused pane to workspace N and shows workspace N. |
send_to_workspace_1 to send_to_workspace_9 | ctrl+opt+N | ctrl+alt+N | Sends the focused pane to workspace N and stays on this workspace. Focus goes to another pane here. |
send_to_workspace_N needs a terminal that reports Ctrl and Alt with a digit.
A legacy terminal sends ctrl+alt+N as alt+N, or as a control character for
most digits. The Kitty keyboard protocol reports the key, and so does xterm's
modifyOtherKeys. Ghostty, kitty, WezTerm and foot speak the Kitty protocol. In
another terminal, bind the action to a key the terminal can send:
[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.
| Action | What it does |
|---|---|
mark_pane | Marks the focused pane, or clears the mark when it is the marked one. The marked pane shows [marked] in its title bar. |
join_marked_left, join_marked_right, join_marked_up, join_marked_down | Moves the marked pane next to the focused one, on that side, from this workspace or another. Needs BSP tiling. |
resize_pane_left_5, resize_pane_right_5, resize_pane_up_5, resize_pane_down_5 | Moves the focused pane's edge by 5 cells. The _20 actions move it by 20. Under the leader, the key repeats without a second leader press, as tmux bind -r does. |
new_workspace | Goes to the first workspace with no pane, the one the dock's + button opens, and opens a pane there. On an empty workspace past the last one in use, that workspace is the new one: it stays there and opens the pane there. |
last_workspace | Goes back to the workspace you were on before this one, as tmux last-window does. Press it again to go back and forth. |
break_pane | Moves the focused pane to the first workspace with no pane and goes with it, as tmux break-pane does. |
last_session | Goes back to the session you were on before this one, as tmux switch-client -l does. |
send_prefix | Sends the leader key to the program in the focused pane, as pressing the leader two times in terminal mode does. Use it for screen's C-a a, or for a tmux in the pane. |
move_workspace_left, move_workspace_right | Swaps this workspace with the one before or after it, and follows it. The two workspaces trade numbers, so the moved one answers to its new number. |
cycle_layout | Cycles BSP, master-stack and scrolling. |
reload_config | Reads config.toml again, as the "Reload config" palette row does. |
toggle_mouse | Stops asking the terminal for mouse reports, so the terminal selects text itself. Run it again to turn the mouse back on. The setting lasts until you quit. |
For tmux's synchronize-panes, bind toggle_multifocus_all. It puts every pane
on the workspace in the multifocus set, so typing goes to all of them. See
LAYOUT_MODES.md.
[keybindings.window_prefix]
mark_pane = ["m"]
join_marked_right = ["J"]Menus nested under the leader
A key in a prefix menu can open a menu of your own, so a keymap can nest as
deep as a tmux which-key tree. You declare the menu (Your menus),
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:NAMEgoes 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_. titleheads the which-key panel and defaults to the name.stickykeeps the menu open after a key runs, as tmuxbind -rdoes, untilescor 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.escandctrl+cclose 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,unbindandfreeread the menus as they read any other section, namedmenus.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], withtitle,stickyand akeystable ofaction = ["key"], is the older spelling of a menu and is still read: its keys are the rows. When both spellings declare one name, tuios uses[menus.NAME]and warns.
Menus in the rail, the Inbox and the other overlays
open_menu:NAME also works in the sections of an overlay: sidebar,
sidebar_files, sidebar_agents, quick_look, quick_look_inside, inbox,
inbox_peek, mail, transfers and review. The menu opens over the
overlay, and its keys run that overlay's own actions, so name actions of the
same section.
[keybindings.inbox]
"open_menu:triage" = ["x"]
[menus.triage]
title = "Triage"
items = [
{ action = "inbox_dismiss", key = "d" },
{ action = "inbox_snooze", key = "s" },
{ action = "inbox_close", key = "c" },
]In the Inbox, x d dismisses the selected item and x c closes the Inbox.
esc closes the menu and leaves the overlay open, and the next key is the
overlay's own again. A menu that the overlay's menu opens runs over the same
overlay. A sticky menu stays open while the overlay does. Copy mode is not one
of these sections: bind its menus in terminal_mode or under the leader.
Split into the same ssh
These actions open a pane on the machine that the focused pane is connected to with ssh:
| Action | What it does |
|---|---|
split_ssh_horizontal | Splits the pane top and bottom. |
split_ssh_vertical | Splits the pane left and right. |
new_window_ssh | Opens a new window. |
The new pane runs ssh again, to the same destination as the same user, with the connection options only.
tuios does not run the remote command again. It also removes -N, -f, -T,
-W, port forwards and the other options that stop a shell. mosh works the
same way.
When the focused pane does not run ssh, the action opens an ordinary pane. You can use the keys in every pane. Some ssh lines also get an ordinary pane. See CONFIGURATION.md.
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.
Keybindings
Every default key in TUIOS for window mode, terminal mode, prefix commands, copy mode and the mouse, and how to change them.
Copy mode and screenshots
Copy mode and screenshots: part of the Keybindings of TUIOS.
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.