Configuration

TUIOS reads ~/.config/tuios/config.toml. If XDG_CONFIG_HOME is set, the file is $XDG_CONFIG_HOME/tuios/config.toml. On the first run, TUIOS writes a config.toml with comments and no settings, except [startup].

tuios config path     # print the path
tuios config edit     # open it in $EDITOR
tuios config reset    # overwrite it with the defaults, after asking

Write only what you want to change. Missing keys and missing tables take their defaults.

config.toml can include other files, and TUIOS also reads the *.toml files in ~/.config/tuios/config.d/. config.toml wins over all of them. See Split the Config.

[appearance]
theme = "nord"

[keybindings.window_management]
new_window = ["ctrl+t"]

Two things live outside the file: custom themes in ~/.config/tuios/themes/ and custom glyph sets in ~/.config/tuios/glyphs/.

Tables

Applying changes

TUIOS watches the file. A save is applied about 200 ms later, with no restart. The command palette also has a Reload Config entry.

A file with an error is not applied. The running settings stay, and the error is shown on screen.

Most of the file applies live. These parts do not:

The daemon also follows the file for [hosts], [agents], [notify] and preferred_shell. Removing a host closes its link at once. A change that gives panes or other machines more waits for tuios config apply. This covers a new host, a wider [agents.permissions] and a wider link policy. See Changes that wait.

Changing a setting at runtime

tuios list-options                       # every path, with default and accepted values
tuios list-options --section sidebar     # one group
tuios list-options --search "pane bg"    # fuzzy search, best match first
tuios get-config appearance.border_style
tuios set-config appearance.border_style thick
tuios config browse                      # search the options and set one, in an explorer

tuios config browse shows each option with its type, default, current value and source. Press / to search. Press Enter on an option to set it the same way as set-config. q or Esc leaves it. It needs a running daemon. See Explorers.

set-config changes a running session. With a client attached, the client applies the value and writes it to the config. With no client attached, the daemon keeps the value for this session. The next client that attaches applies it and writes it to the config. A path the registry does not know is refused. An [appearance] option also answers to its bare name, so border_style and appearance.border_style are the same path. set-config cannot reach [keybindings], [hooks], [hosts], [tailscale], [agents] or the [dock] lists, because those are maps and lists rather than single values. For [agents] this is also a safeguard: a program in a pane cannot loosen it through TUIOS. dock.clock.format is the one [dock] key it can set.

The in-app settings page

The settings page edits every option in the registry, in the same groups list-options prints. Open it with:

• , in window mode (open_settings)
• Ctrl+B , (prefix_settings)
• Settings in the Ctrl+P command palette

Most rows apply as you change them. Colour options open a colour picker. Two rows open editors of their own: the rail's sections and the dock's components.

The page reopens on the tab, row and search you left it on. 1 to 9 go to a tab. A row whose value in force differs from its default has a dot after its name. That includes the rows the page draws by hand, such as the theme, glyph set, shared borders, pane gap, the master and column ratios, the rail's sections, max FPS, show keys, spotlight and the screen saver effect. For the pane geometry rows the value compared is the session's, not the config's. Backspace (or Delete) resets a changed row to its default, and its description says what the default is. The hand-drawn rows have no reset: Backspace on one says so, and you change it back with its own control. Ctrl+Z undoes the last change made on the page.

/, or any letter the page does not use, searches every tab. It ranks each row by its name, its config key, its value and its description, and each result names its tab. In the results, ←, → and Enter change the row where it is, Tab goes to the row on its own tab, and Esc clears the search. The command palette reaches the same rows by name (settings: pane background), and tuios list-options --search runs the same search from a shell.

Command-line flags

Interface flags override the file for one run. They are accepted by tuios, tuios new, tuios attach, tuios ssh and tuios tape play.

Appearance

All keys below go under [appearance].

Theme and chrome

animations_enabled, the key motion replaces, is still read from older files: false reads as motion = "none", and true changes nothing. Where both are set, motion wins.

border_style

Values: rounded (default), normal, thick, double, block, outer-half-block, inner-half-block, ascii, hidden, glyphs.

glyphs uses the border of the active glyph set. hidden also hides the window buttons and the scrollbar, because both are drawn on the border.

Focused border colour

The focused pane's border shows the mode. By default it is the theme's cyan in window mode and its green in terminal mode. Three keys set it:

[appearance]
border_focused_color_window = "accent"
border_focused_color_terminal = "#ff9e64"
# border_focused_color = "#89b4fa"   # both modes

• A key for one mode wins over border_focused_color in that mode.
• An empty key uses the next key. After the three keys, the theme sets the colour.
• A value is a hex colour, a palette index from 0 to 255, a slot name such as blue, or a role name such as accent.
• border_focused_color also replaces the colours for copy mode and for an agent that waits. The keys for one mode do not.
• Added in v0.11.0 On many themes the cyan and the green have the same lightness. When you set no colour, the terminal-mode border is then a step darker, or a step lighter when darker is too faint. You can see the mode without the hue. To keep one colour for both modes, set border_focused_color.
• At 16 colours the default borders use bright cyan and bright green from your terminal's palette.

The settings page has a row for each key, in the Appearance section. See Border colours.

Dialog and panel frames Added in v0.11.0

The small dialogs, such as rename, confirm and new space, draw their frame in border_style. The large panels, such as the command palette, the switchers, the Agents view and the settings page, have no frame. Set frame_panels = true to give them the same frame.

[appearance]
border_style = "double"
frame_panels = true

• rounded, normal, thick, double and ascii draw their own corners and lines.
• hidden draws no frame. A dialog keeps its size, and its title and key hints stay in place. A frame that is the only edge of a region is drawn as rounded. An example is a panel at 16 colours.
• block, outer-half-block and inner-half-block draw the rounded frame.
• glyphs draws the border of the active glyph set.
• At 16 colours a panel always has a frame, because its background is the background of your terminal.

appearance.pane_overlays Added in v0.12.0 draws dialogs and panels like pane windows. Every panel gets a frame in the focused pane's border colour. The frame and its content sit on the background of an empty pane cell. The selected row and input fields are steps of that background. The option is off by default. Under hidden, at 16 colours, or with no theme on a terminal that reports no background, a dialog keeps its shade.

appearance.overlay_border_color Added in v0.12.0 sets a colour for every dialog and panel frame: #89b4fa, a slot name such as bright_cyan, or a role such as accent.

[appearance]
pane_overlays = true
overlay_border_color = "accent"

max_fps

max_fps is the highest frame rate TUIOS draws at. Your terminal and your monitor can show fewer frames. A value above what they can show does not make TUIOS smoother.

[appearance]
max_fps = 144       # a number from 10 to 240
# max_fps = "auto"  # the refresh rate of your display
# max_fps = 0       # 60, the default

The settings page offers Auto, 30, 60, 90, 120, 144, 165 and 240. With Auto selected, the row shows the rate in use, for example Auto (144). A change applies at once, with no restart.

• What you see. TUIOS sends a frame to your terminal, and the terminal draws it on its own schedule. kitty and Ghostty draw at most once for each refresh of the monitor, so a 60 Hz monitor shows at most 60 frames a second. Over SSH, the network and the remote terminal set the limit too.
• What it costs. TUIOS draws only when something on the screen changes. The terminal library under it still wakes at max_fps while TUIOS is idle. An idle TUIOS at 240 wakes about three times as often as at 60.
• How auto finds the rate. TUIOS looks once in the background when it starts, and again when the config file reloads. Until the answer arrives, it draws at 60. On Wayland it asks hyprctl on Hyprland, niri on niri and wlr-randr on other wlroots compositors. On X11, or on another compositor, it asks xrandr --current. On macOS it asks system_profiler SPDisplaysDataType. On Windows it does not look, and uses 60.
• Several displays. A terminal window cannot tell which display it is on, so auto uses the highest rate among them.
• Remote clients. Over SSH, in tuios-web and in the SSH server, auto uses 60, because the displays on the machine are not the ones you see.

Backgrounds

A cell with no background of its own is transparent, so your terminal's own background shows through. That is the default everywhere: pane content left on the default background, the space between panes, the borders, the dock and the rail. These options paint those cells instead, one surface at a time or all at once.

Each takes off, theme or a #RRGGBB colour:

• off paints nothing, so your terminal's background shows through.
• theme paints the active theme's background, with the theme's foreground on default-coloured text. With no theme set, it behaves as off.
• #RRGGBB paints that colour. With a theme set, default-coloured text takes the theme's foreground, lightened or darkened until it reads on the colour.

A surface's own option wins whenever it holds a value, off included. Left empty, it follows background:

[appearance]
background = "theme"          # every surface on the theme's background
dock_background = "#11111b"   # the dock a shade darker
pane_background = "off"       # panes keep the terminal's own background

[appearance.sidebar]
background = "#181825"

Only cells with no background of their own are painted. A background a program chose, the selection and search marks, and the colours the chrome sets itself always win. A value that is not a keyword or a #RRGGBB colour reads as off for that surface, with a validation warning.

While the pane background paints a colour, a program that asks the terminal for its colours (OSC 10 and 11) is told the colours it is drawn on, so it can pick a light or dark palette. All six options apply live, reach every attached client, and are on the Backgrounds tab of the settings page, where x clears a surface back to following background.

Windows and titles

window_title_format

A template for every title. It expands three placeholders:

• {title}: the custom name, or the title the program set
• {index}: the window's 1-based position in its workspace
• {cwd}: the window's working directory

[appearance]
window_title_format = "{index}: {title} ({cwd})"

Any other {...} produces a validation warning and is drawn as written.

host_title

host_title sets the title of the terminal that tuios runs in, such as the title bar of Ghostty. It is the same as set-titles in tmux. The title follows the focused pane, the workspace and the session, and it changes when the pane's own title changes.

[appearance]
host_title = "{title} · {session}"

• With no focused pane on the workspace in view, the title is the session's name.
• The title is also the session's name when the template uses {title} and the pane has no name, as for a new shell, and when the template comes out empty.
• A title that a tool sets with herdr's terminal title set wins while it is set.
• Each client sets the title of its own terminal.
• When you empty the option while a client is attached, tuios clears the title that it set.

The option is on the settings page, in the Appearance section. tuios set-config applies it at once.

Mouse and input

Links

Ctrl+click on a link opens it. Ctrl+drag still moves the pane: a link opens only when the pointer does not move. Only http, https, mailto, ftp and ftps links go to the opener. TUIOS copies other links. Under ssh, on a remote client, or on a machine with no desktop, TUIOS copies the URL, and your terminal can still open the link from the OSC 8 that TUIOS writes. If the opener fails, the dock says so and TUIOS copies the URL. See Links for the opener, the safety rules and a table of terminals.

Scrolling

Tiling and zoom

The layout a new session starts in is startup.layout. See The startup table. Each workspace starts with the master-stack options, and the layout keys change the workspace on screen. See Master-stack.

Dock

dock_workspace_label_max stops one long workspace name from pushing the other tabs off the dock. Set it to 0 to show the whole name. The workspace strip then scrolls. A dock with no room for one full tab still shows the current tab, cut to fit.

dock_compact works with the dock at the top and at the bottom. It has no effect when dockbar_position is hidden. The change applies at once. A compact dock does not show the rule that tells how long a dock message stays. When clients with different docks share a session, the panes keep the largest dock height. A client with a compact dock shows a blank row in that case.

The mode pill icons can be any text up to 8 cells wide. A wide character, such as 終, counts as two cells. The dock does not accept control characters. For an icon that it does not accept, the dock shows the default icon and the config check shows a warning. The pill adds one space on each side of the icon. If an icon is empty and the mode has no other text, the dock shows no pill in that mode. While tiling is on, the pill also shows the next split direction, V or H. Set dock_mode_split_letter = false to show the tiling icon alone. With the default icons, the pill then has the same width as the pill of the leader key, so the workspace tabs do not move when you press the leader.

[appearance]
dock_mode_icon_window = "WM"
dock_mode_icon_terminal = ">_"
dock_mode_icon_tiling = ""

To remove the whole mode pill, remove "mode" from the left list in the [dock] table. You can also set the icons on the settings page, in the Dock section, or with tuios set-config appearance.dock_mode_icon_window WM. The change applies at once.

Workspace tab style Added in v0.10.0

By default the workspace strip draws rounded pills. [dock.tabs] can draw flat tabs, the way a tmux status line draws its window list:

[appearance]
dock_workspace_tab_format = "{name}{zoom} {icon}"

[dock.tabs]
style         = "flat"        # pill (default) or flat
separator     = " • "         # drawn between flat tabs
separator_fg  = "#4c3743"
active_fg     = "#272e33"
active_bg     = "#a7c080"
active_bold   = true
inactive_fg   = "#4f5b58"
number_glyphs = ["I", "II", "III"]  # {icon}: the first entry is workspace 1
zoom_marker   = " [ ]"        # {zoom} on the current workspace while a pane is zoomed
show_add      = false         # keep the "+" tab in the flat style

Colours are #rrggbb, and they are overrides. With no colour set, a flat strip draws the current tab in bold on the theme's accent, and the other tabs in dim text. tuios ignores a colour that is not #rrggbb and shows a warning. The flat style shows even one workspace, and drops the + tab unless show_add is on. With no [dock.tabs] table, the strip does not change.

active_fg, active_bg, inactive_fg, inactive_bg and inactive_bold also apply to pills. A pill with no colour keeps the theme's look.

appearance.dock_mode_pill Added in v0.12.0 sets what the mode pill shows while tiling is on. tiling (the default) shows the tiling icon. input shows the terminal icon or the window icon, and the split letter after it shows that tiling is on.

To reorder the dock or add your own cells, see The dock table.

Calm mode Added in v0.12.0

appearance.calm turns calm mode on. Nothing moves or blinks, and only the messages that need you show in the dock. Ctrl+B Z turns it on and off and saves the choice here. Calm mode sits over appearance.motion. When you turn calm mode off, your motion level comes back. Calm mode and appearance.motion = "none" also stop the motion of TML surfaces. A surface then shows each part at once.

[appearance]
calm = true

Rail options

Two rail options sit directly in [appearance]:

The rest are in [appearance.sidebar].

The scrollbar

[appearance.scrollbar]:

Selection colours

[appearance.selection] sets the colours TUIOS draws over pane content to mark text.

An empty foreground keeps the colour the program wrote. An empty background falls back to the default.

Clipboard writes from a pane

A program in a pane sets the clipboard with OSC 52. An editor uses OSC 52 to yank over ssh. Any output can also carry OSC 52, for example a file that a program prints. appearance.selection.osc52_write controls what happens.

[appearance.selection]
osc52_write = "focused"

• When the focused pane copies text with a line break or a control character, the dock shows one line for that pane. A one-line copy shows nothing.
• Each pane keeps one clipboard ask. A click copies only the text that the dock shows. If the text changes first, click the new message.
• A pane that runs without the daemon keeps its own copy of the text. The program reads it back with an OSC 52 query. A pane under the daemon keeps no copy, so an OSC 52 query there always gets an empty answer.
• TUIOS drops a clipboard reply that answers no read request of TUIOS.

Pastes, notifications, OSC 66 text and link addresses lose their control characters. A paste into a pane keeps its tabs and line breaks. Text that holds ESC[201~ cannot end a bracketed paste early.

The session rail

[appearance.sidebar] configures the rail at the side of the screen.

Deprecated keys still load: show_windows, show_agents and workspaces in this table, and the flat sidebar_* keys in [appearance]. They are folded into the current keys when the file is read.

sections

One string sets which sections the rail draws, their order from the top, and the share of the rail each may take.

[appearance.sidebar]
sections = "sessions:25,terminals,files:25,agents:34"

• Separate sections with commas. Add :N for a share in percent.
• The section names are sessions, terminals, files, agents, git and custom. Leave a name out to hide that section. See The custom section.
• A share is a ceiling, not a reservation. A section only takes the lines its rows fill. A section with no share takes what the others leave.
• spacer draws nothing and takes lines. It is the only name you can repeat. A spacer with a share keeps that share. A spacer with no share takes the lines nothing else wants, which pushes what follows to the bottom.

[appearance.sidebar]
# Sessions at the top, files at the bottom
sections = "sessions:30,terminals,spacer,files:40"

An unknown name, a bad percent or a repeated section is dropped and reported as a config warning.

The settings page has an editor for this: the Sections row under Sidebar. Arrows select, Shift+arrows move, Enter adds or removes a section, ←/→ change the share, r restores the default and u undoes your edits.

The files section

The files section lists the focused pane's directory. It is read again when the shell changes directory, when the focus moves and when a client attaches. It is also read again when a file in the listed folder is added, removed or renamed, by the pane or by another program. tuios asks the system to report these changes (inotify on Linux, kqueue on macOS and the BSDs, ReadDirectoryChangesW on Windows). Nothing polls, and a change to the contents of a file does not cause a read. For a pane on another machine, the list changes only when the shell changes directory.

folder_click decides what a click on a folder does: navigate opens it in the listing, cd sends the focused pane there, both does both. A cd is only typed into a pane that is at a shell prompt.

The file keys are in [keybindings.sidebar_files] and work while the rail has the keyboard and the cursor is on a file row. See Keybindings. Each action opens a centred dialog. The delete dialog opens on Cancel, so Enter on an untouched dialog deletes nothing.

Delete uses the freedesktop.org trash in your home directory, so your desktop's trash shows the file and can restore it. D deletes permanently. Set file_delete = "permanent" to make d permanent too. The per-volume trash is not implemented.

Y copies the absolute path of the selected file or folder. A folder's context menu has a Copy path row that does the same.

On Windows, a shell under MSYS2 or Cygwin reports its folder as /c/work. TUIOS reads that as C:\work, by the rules of cygpath, so the files section lists the right folder.

appearance.sidebar.file_drag Added in v0.12.0 lets you drag a row of the files section onto a pane. It is on by default. See Drag a file into a pane.

The file editor

Shift+Enter on a text file opens it in a terminal editor. editor sets the command. The settings page shows it as File editor under Sidebar.

[appearance.sidebar]
editor = "micro"

• Other terminal editors and arguments work too, such as nano or vim -f.
• Quote a path or an argument that contains spaces. TUIOS splits the command into arguments and runs no shell.
• TUIOS adds the full path of the file at the end.
• When editor is empty, TUIOS uses $EDITOR, then $VISUAL, then vi.
• File links and hints open files with the same command.
• TUIOS reads the first 512 bytes of a file to check that it is text. It refuses binary files and special files.

The custom section

The custom section shows the output of a command you write. Place custom in sections and describe it in [appearance.sidebar.custom]:

[appearance.sidebar]
sections = "sessions:25,terminals,custom:35,agents:30"

[appearance.sidebar.custom]
title   = "Brief"
command = "agent-brief render"
refresh = "event:window-focused,agent-state"

The command follows the rules of a dock component. It runs in the client, under a three second timeout, with bounded output. SGR colour stays, and every other control sequence is removed. A command that fails, times out or prints nothing leaves the title over an empty section. Five failures in a row stop it until the config reloads or you run tuios refresh-dock rail/custom. tuios list-dock-components lists it as rail/custom. Rows are cut to the rail's width and to the section's lines, with … +N for the rows below.

Each run gets the client's environment and these variables: TUIOS_SESSION, TUIOS_SOCKET, TUIOS_RAIL_SECTION (custom), TUIOS_RAIL_WIDTH, TUIOS_RAIL_HEIGHT, TUIOS_ACTIVE_PANE_ID and TUIOS_ACTIVE_PANE_CWD. An event that arrives during a run causes one more run after it, so a quick focus change never leaves the old pane's rows on screen. The command does not run while the rail is hidden or folded.

sections works with tuios set-config. [appearance.sidebar.custom] is read from the file only, so a program in a pane cannot change the command.

The pane section Added in v0.12.0

The rail can show a live terminal under its own heading. Put pane in sections, and describe it in [appearance.sidebar.pane]. tuios reads this table from the file only.

[appearance.sidebar]
sections = "sessions:25,terminals,files:25,pane,agents:34"

[appearance.sidebar.pane]
title   = "git"
command = "watch -t git status -sb"
height  = 12

See The pane section.

Group the main checkout Added in v0.12.0

appearance.sidebar.group_main = true puts a repository's main checkout under the repository row with its worktrees. The session is labelled by its branch. Enter or a click on the repository row then opens the main checkout's session. Fold group on the row's right-click menu folds the group. The default is false.

Session peek Added in v0.12.0

When the pointer or the rail cursor is on a session row, the terminals section shows the panes of that session. appearance.sidebar.peek = false turns this off. The terminals section then shows the panes of the attached session.

Two edges Added in v0.9.3

The rail can show on both edges of the screen at the same time. [appearance.sidebar] still configures the original rail. Add [appearance.sidebar.left] or [appearance.sidebar.right] to configure one edge:

[appearance.sidebar]
position = "right"
sections = "sessions,terminals,custom"

[appearance.sidebar.custom]
command = "right-summary"

[appearance.sidebar.left]
enabled = true
width = 28
sections = "sessions,files,custom"

[appearance.sidebar.left.custom]
command = "left-summary"

• On the edge of position, the edge table overrides only the keys it sets. The other keys come from [appearance.sidebar].
• On the other edge, a key you do not set takes its default. An unset sections takes the default section order.
• With position = "hidden", an edge table with enabled = true still draws. When both edges are on, the left one is the original rail.
• Each rail has its own scroll, keyboard focus and custom command. Both read the same sessions, files and git state.
• On a narrow screen, the second rail closes before the original rail.

Each edge table also takes the five subagent_* keys. A key that the edge table does not set uses the value from [appearance.sidebar]. See Subagent rows.

The edge tables are read from the file only. tuios set-config cannot change them, because a custom command runs outside the panes. Ctrl+B H shows or hides the second rail. See Session Rail.

Agent rows

[appearance.sidebar.agent_row] chooses which tokens an agent row shows and styles each one, with optional rules that match on the token's value:

[appearance.sidebar.agent_row]
tokens = ["session", "need", "harness", "name", "elapsed", "context", "subagents", "pr", "meta", "now", "message"]

[[appearance.sidebar.agent_row.elapsed.rule]]
gt = 30          # minutes in the current state
fg = "warning"

The tokens above are the shipped list. The other tokens are state, host and prompt. A tokens list you wrote keeps its own order and gets no new tokens, so add subagents or pr to it to see them. need says what a row wants from you, such as approval or question. context shows ctx 84% once the agent's context is 80% full. now is what a working agent is doing, such as Bash: go test ./.... subagents shows how many subagents a Claude Code agent has at work, such as 3 subagents, on any row while any run. When the subagents have rows of their own, it reads 3 of 4 run. pr shows the pull request of the session's worktree branch and its checks, such as PR #12 open pass. meta draws the other keys the pane reported with tuios set-agent-meta, and $ followed by a key, such as $model or $cost, places one key. See Session Rail.

Each rule has one test: equals, contains, starts_with, gt or lt. The first matching rule wins. A mistake in this table is a warning, not an error.

Splits that follow ssh

The actions split_ssh_horizontal, split_ssh_vertical and new_window_ssh open a pane on the machine that the focused pane is connected to with ssh. See Keybindings.

appearance.new_window_follow_ssh makes the ordinary actions do the same: split_horizontal, split_vertical and new_window. When the focused pane does not run ssh, these actions open an ordinary pane. The default is false.

[appearance]
new_window_follow_ssh = true

tuios finds ssh in the foreground of the pane. ssh can run from a shell, or from sshpass, autossh or mosh. tuios reads only the processes that you own in the pane. It runs the ssh or mosh that it finds on its own PATH, with no shell on this machine. It never runs the program that the pane runs.

The new ssh gets the same environment as an ordinary new pane. If the ssh that tuios follows has an SSH_AUTH_SOCK that names your own agent socket, the new ssh gets that value too. An agent that your shell started in the pane then works in the split. The socket must not be a link, and its folder must be yours and closed to other users.

The new ssh line keeps only what it needs to reach the same host as the same user. It always gets -o ControlMaster=no. Your ~/.ssh/config applies to it as usual, so a setting that you put there still works in the split.

Lines that are not followed

tuios follows an ssh line only when each -o option is on one of two lists. The new pane keeps these options:

AddressFamily, BatchMode, CertificateFile, CheckHostIP, Ciphers, Compression, ConnectionAttempts, ConnectTimeout, EscapeChar, HostKeyAlgorithms, HostName, IdentitiesOnly, IdentityFile, KbdInteractiveAuthentication, KexAlgorithms, LogLevel, MACs, PasswordAuthentication, Port, PreferredAuthentications, ProxyJump, PubkeyAcceptedAlgorithms, PubkeyAuthentication, ServerAliveCountMax, ServerAliveInterval, StrictHostKeyChecking, TCPKeepAlive and User.

The new pane does not get these options, and tuios still follows the line:

• Forwards and sessions: LocalForward, RemoteForward, DynamicForward, GatewayPorts, ExitOnForwardFailure, ClearAllForwardings, Tunnel, TunnelDevice, RemoteCommand, SessionType, StdinNull, ForkAfterAuthentication and RequestTTY.
• Files, sockets, environment and forwarding: ControlMaster, ControlPersist, ControlPath, UserKnownHostsFile, GlobalKnownHostsFile, HostKeyAlias, IdentityAgent, SendEnv, SetEnv, ForwardAgent, ForwardX11 and ForwardX11Trusted.
• The flags -A, -X, -Y, -S, -L, -R, -D, -W, -w, -N, -f, -n, -T, -t, -M and -s.

These ssh lines get an ordinary pane:

• An -o option that is not on the two lists above. ProxyCommand, LocalCommand, XAuthLocation and Match are examples.
• An option or a value with a control character, such as a line break.
• -E, -F, -I, -G, -V, -Q and -O, and an option that tuios does not know.
• A -J or ProxyJump hop that is not [user@]host[:port] or the ssh:// form, made of letters, digits and ._:@[]-, or a hop that starts with -.
• A mosh destination that starts with -.
• mosh with --ssh, --client or --server.
• ssh that another program starts, such as scp, rsync, git or sftp.

Put a ProxyCommand or a ProxyJump in ~/.ssh/config to use it with a split. A split with -J on the command line is followed.

Start in the remote folder

The new pane starts in the remote folder when the remote shell reports its folder with OSC 7. The host name in the report must be the same as the host in the ssh line, or as the HostName that ssh -G gives for that line. reachy-mini matches pollen@reachy-mini. When ~/.ssh/config makes prod an alias for box.example.com, a report from box.example.com or from box matches ssh prod. A report from box.other.com does not. When there is no match, the new pane starts in the remote home folder.

fish sends the report by default. For bash, add this line to ~/.bashrc on the remote machine:

PROMPT_COMMAND='printf "\033]7;file://%s%s\033\\" "$HOSTNAME" "$PWD"'${PROMPT_COMMAND:+;$PROMPT_COMMAND}

For zsh, add these lines to ~/.zshrc on the remote machine:

autoload -Uz add-zsh-hook
_tuios_osc7() { printf '\e]7;file://%s%s\e\\' "$HOST" "$PWD" }
add-zsh-hook precmd _tuios_osc7

To go to the folder, tuios adds -t, -o RemoteCommand=none and the command exec sh -c 'cd "FOLDER" ...' to ssh. This works with every login shell that can start sh. If the folder is gone, the new pane starts in the home folder. A folder name with a quote, $, a backslash or ! is not used. A Windows folder, such as C:/Users/x or a network share //server/share, is not used either, because a Windows ssh server has no sh. The new pane then starts in the home folder.

Glyph sets

A theme sets the chrome's colours. A glyph set sets its shapes: border corners, window buttons, rules, separators and rail marks.

[appearance]
glyphs = "heavy"

tuios list-glyphs            # every set, and every role name
tuios list-glyphs heavy      # what this set draws, role by role
tuios set-config appearance.glyphs heavy

A set's border is used only when border_style = "glyphs". This keeps a set from silently overriding a border style you chose. A set that defines only some border runes gets the rounded border for the rest.

Writing a set

A set can name the marks of the agent states: state_working, state_needs_input, state_idle, state_done, state_errored, state_unknown and state_waiting. A mark may be one cell or two, so state_needs_input = "✋" is valid. A state the set leaves alone keeps the shipped mark. Of the built-in sets, only ascii names these marks.

Save <id>.json in the glyphs directory. tuios list-glyphs prints its path.

{
  "display_name": "Mine",
  "inherits": "heavy",
  "bullet": "◦",
  "focus": "▐",
  "border": {
    "top_left": "╔",
    "top_right": "╗",
    "bottom_left": "╚",
    "bottom_right": "╝"
  }
}

Every field is optional. The id defaults to the file name. A role you do not set comes from the inherited set, and finally from default. Inheritance goes up to eight levels deep.

The roles:

• Window buttons: close, maximize, minimize, dot, pill_left, pill_right
• Rules and separators: rule, separator, arrow_left, arrow_right, dash_rule
• Rail marks: focus, attention, bullet, add, collapse, expand, fold_open, fold_shut, tree_branch, tree_last
• Files section: folder, parent, file
• Scrollbar: scrollbar_thumb, scrollbar_track
• Text: ellipsis, sigil
• Border: border.top, border.bottom, border.left, border.right, the four corners, and the junctions middle, middle_top, middle_bottom, middle_left, middle_right

Most roles must be exactly one cell wide, because the window buttons' click areas are fixed offsets. A glyph of the wrong width falls back to the default. separator, ellipsis, collapse and expand may be any width. To see what was dropped:

tuios list-glyphs mine --json | jq -r '.problems[]?'

The directory is read again on every lookup, so a new file can be selected at once. A file that does not parse is skipped and listed under problems.

--ascii-only replaces non-ASCII glyphs role by role, so a set keeps every role it already spelled in ASCII. A glyph set never changes colours, and it does not change the dock's icons.

Added in v0.11.0 A session name, a workspace name or a pane title can hold Nerd Font icons. TUIOS shows each icon in one cell, on the rail, in the dock and in the rest of the chrome. On the Linux console and under --ascii-only, TUIOS removes the icons from what it draws, because they show as empty boxes there. The name itself does not change.

The settings page has a Glyph set row under Theme. Its picker applies each set as you move through the list.

Themes

345 themes ship with TUIOS.

tuios --list-themes                   # every theme id
tuios --preview-theme dracula         # the 16 ANSI colours
tuios list-themes --filter gruvbox    # from a running daemon, with --json
tuios list-themes catppuccin_mocha    # colours and their contrast

[appearance]
theme = "dracula"

With no theme, TUIOS uses your terminal's own colours. A theme only changes ANSI colours 0 to 15. 256-colour and truecolor output is drawn as the program wrote it.

To pick one in the app, press Enter on the Theme row of the settings page, or choose Theme Picker in the command palette. The picker previews as you move and Esc restores the theme you had. It has no key binding.

Custom themes

Save one theme per JSON file in ~/.config/tuios/themes/. Subdirectories are ignored.

{
  "id": "my-theme",
  "display_name": "My Theme",
  "fg": "#e0def4",
  "bg": "#191724",
  "black": "#26233a",
  "red": "#eb6f92",
  "green": "#31748f",
  "yellow": "#f6c177",
  "blue": "#9ccfd8",
  "purple": "#c4a7e7",
  "cyan": "#ebbcba",
  "white": "#e0def4"
}

• id defaults to the file name, lowercased. display_name defaults to id.
• The colour names are black, red, green, yellow, blue, purple, cyan, white, each with a bright_ variant, plus fg, bg and cursor. Note purple, not magenta.
• A missing colour gets the xterm default. A missing bright_* colour copies its normal colour, so set them if you want bright text to look different.
• An optional chrome object sets the UI colours directly (accent, accent_bright, success, warning, error, info, surface) without changing the pane palette.
• A file that does not parse is skipped and logged.

tuios import-theme <file> converts a kitty, Ghostty, Alacritty or WezTerm scheme into a file here.

Selecting an id that is not registered yet, with set-config or the settings page, reads the directory again first. So does tuios list-themes. The picker builds its list when it opens.

Notifications

[notifications] sets how long messages stay on screen, how they look and which ones the dock shows. For a time, 0 uses the built-in default: 2 seconds for info and success messages, 8 for warnings and 15 for errors. A time can be up to 3600 seconds.

A message that level hides still goes to the log viewer (Ctrl+B D l). Warnings and errors always go to the log. A message from a pane, an agent or mail does not use level. [notifications.agent] and [notifications.mail] control those messages.

The pane bell Added in v0.11.0

A program in a pane rings the bell when it prints the BEL character. For example, printf '\a' rings it. notifications.bell sets what TUIOS does then:

[notifications]
bell = "forward"   # or "toast", "both", "off"

• TUIOS sends the bell for every pane, also for the pane you are in. It sends at most one bell from each pane in 200 milliseconds.
• Each client sends the bell to its own terminal. Over tuios ssh and in tuios-web, the bell goes to that client, not to the machine that runs TUIOS.
• Your terminal decides what a bell does. In Ghostty, for example, set bell-features to choose a sound, an attention request or a title mark.
• The workspace bell marker does not change with this setting. Set bell_marker under [dock.tabs] to change it.

The settings page has this setting in the Alerts tab, as "Pane bell".

Agent alerts

[notifications.agent] controls what happens when an agent in a pane changes state.

[notifications.agent.states] turns alerts on per state: needs_input, errored and done default to true. idle and working default to false.

To hear an alert, set sound = true. sound_mode then decides how:

• audio plays a short cue through the audio player of the machine that runs TUIOS: paplay, pw-play or aplay on Linux, afplay on macOS, PowerShell on Windows. If the machine has no player, the alert is silent and TUIOS shows no message.
• bell sends a BEL character to your terminal. Your terminal decides what a bell does, and some terminals make no sound. In kitty, check that enable_audio_bell is yes. Other terminals have a similar bell setting.
• both does the two.

Over SSH or in the browser, audio plays on the server, not where you sit. Use bell there. See Agents.

[notifications.agent.sounds] replaces the two built-in cues with your own files: needs_input (also used for errored) and done (also used for idle). A path that does not exist falls back to the built-in cue.

The after-agent-state hook follows the same rules, including the settle wait.

Mail alerts

[notifications.mail] controls the alerts for mail to you and for session notices. A key that you leave out uses the same key from [notifications.agent].

TUIOS warns when between_agents is on and mail alerts are off.

The sound mode, the cooldown, the cue files and the quiet hours always come from [notifications.agent]. tuios set-config notifications.mail.sound "" clears a key, and get-config then prints (follows notifications.agent.sound). See Agent Messaging.

Keybindings

leader_key

The prefix key. The default is ctrl+b.

[keybindings]
leader_key = "ctrl+a"

alt+space is already the app launcher.

opt+ and option+ mean alt+ on every platform, cmd+ and command+ mean super+, and control+ means ctrl+. See Modifier spellings. Press the leader two times in terminal mode to send it to the pane.

If TUIOS cannot read the leader, the leader is ctrl+b until you correct it. See When a key is wrong.

lock Added in v0.11.0

Lock mode gives every key in terminal mode to the pane, except the leader.

[keybindings]
lock = true

See Lock mode.

nest_exit_key Added in v0.12.0

The key that ends nest mode. The default is "f12". A key tuios cannot read goes back to "f12", and a key that programs type is reported as a problem.

Sections

Each section is a table under [keybindings]. Each action takes a list of keys. The Keybindings page lists every default.

Key syntax

• Modifiers: ctrl+, alt+, shift+, super+. Also opt+ and option+, which mean alt+, cmd+ and command+, which mean super+, and control+, which means ctrl+. These spellings work on every platform.
• Special keys: enter, return, esc, escape, tab, space, backspace, delete, up, down, left, right, home, end, pgup, pageup, pgdown, pagedown, f1 to f12.
• Any single character: letters, digits, symbols, and accented letters.
• Held modifiers: leftalt, rightalt, leftctrl, leftsuper and the like, for hold_window_mode only. They need the Kitty keyboard protocol.

super+ only reaches TUIOS in terminals that speak the Kitty keyboard protocol. On Linux, opt+1 is alt+1. See One config on macOS and Linux.

new_window = ["n", "ctrl+t"]   # several keys for one action
close_window = []              # no key: the key goes to the pane

An empty list is different from a missing line. A missing action gets its default back at the next load. An empty list stays empty.

shift+1 and ! are the same key, and so are shift+a and A. Binding one spelling binds both. Do not bind the two spellings to different actions.

Keyboard layout and Option characters

[keybindings]
keyboard_layout = "us"   # us, other
option_glyphs = "auto"   # auto, alt, bind, type

See Shifted digits and AZERTY and One Option key for typing.

Platform defaults

On macOS, the workspace and preselect defaults use opt+, and terminal_mode adds opt+tab, opt+shift+tab and opt+esc. Writing alt+ on macOS works but gives an advisory warning. Elsewhere the defaults use alt+. See Keybindings.

The daemon table

A change to single_client, ssh_agent or display in the file applies to the next attach.

The display of the client Added in v0.9.3

A daemon that a host link starts over ssh has no WAYLAND_DISPLAY or DISPLAY. Its panes have none either, so wl-copy, wl-paste, xclip and image paste fail. With display = "follow", the default, the new panes of such a daemon get the display of the local client that attached to the session or used it last.

[daemon]
display = "follow"

• A daemon that has a WAYLAND_DISPLAY or a DISPLAY of its own keeps it. The option does nothing then.
• Each session has a link to the Wayland socket of the client: wayland-<session id>.sock, in the folder of the daemon socket. A new pane gets WAYLAND_DISPLAY set to the full path of the link. The link moves to the socket of the newest client.
• A new pane also gets DISPLAY and XAUTHORITY of the client. DISPLAY is a name, not a path, so a pane keeps the value it started with.
• A shell that started before a desktop client attached has no display. Run eval "$(tuios display-env 2>/dev/null)" in that shell, or add the line to your shell rc. See tuios display-env.
• When the client detaches, the session uses the display of the client before it. When no attached client has a display, tuios removes the link, and new panes get no display.
• tuios uses the display of tuios attach and tuios new only. The client must run on this machine, as your user, and outside every pane. tuios ignores a client that comes through a host link, a client of the tuios SSH server and a client of tuios-web.
• A WAYLAND_DISPLAY name such as wayland-1 is looked up in the XDG_RUNTIME_DIR of the client, then in the one of the daemon, then in /run/user/<uid>. The client does not need XDG_RUNTIME_DIR.
• The Wayland socket must be a Unix socket that you own. DISPLAY must be :N or :N.S, and tuios ignores a forwarded display such as localhost:10.0. XAUTHORITY must be a file that you own.
• The option is read from the file only. tuios set-config cannot change it.

To change window_size for one session while it runs, use tuios set-config daemon.window_size smallest -s NAME. That value is not saved to the file. A change in the file applies when the daemon starts again.

tuios set-config daemon.log_level messages changes the level of a running daemon at once. verbose and trace also log pane content, window titles and paths. tuios logs reads the log.

The startup table

[startup] decides how a new session starts. It never changes a running session.

session and window change a plain tuios only. Other commands use the session you give them. session uses the daemon even when daemon is false.

--standalone and TUIOS_NO_DAEMON=1 override daemon for one run or one shell. If the daemon will not start, a bare tuios runs standalone and says so.

A session keeps its own layout once it is running. Attaching never rearranges a session to match your config.

The workspaces table

When the last pane on the workspace on screen closes, TUIOS shows the workspace you came from. This happens when the pane's program stops, when you close the pane, when tuios xpanes -ss closes it, and with tuios close-workspace.

TUIOS goes back in this order:

1. For a workspace that tuios xpanes opened, the workspace where you ran tuios xpanes.
2. The workspace you showed last that still has panes. After a chain of empty workspaces, TUIOS goes back past each one.
3. The workspace with the lowest number that has panes.

When no workspace has panes, TUIOS shows the splash screen. The workspace on screen is the same for every client of the session, so every client goes back. A pane that moves to another workspace does not close, so TUIOS does not go back.

[workspaces]
return_when_empty = false

The daemon reads the setting when it starts and when the file changes. tuios set-config workspaces.return_when_empty false changes it while TUIOS runs.

A pane on an empty workspace

By default, a workspace with no panes shows the splash screen. To open a pane there when you switch to it, as tabs do in other multiplexers, turn on new_window_when_empty:

[workspaces]
new_window_when_empty = true

The new pane starts in the folder of the pane that had focus on the workspace you came from. It starts in the session's start folder (the folder that tuios new --cwd gave) when you came from a workspace with no pane, from a scratch terminal, or from a pane on another machine. With appearance.new_window_follow_ssh = true, a pane that runs ssh gives a new pane that runs the same ssh, as the new-window key does.

A pane opens only when you switch: with a workspace key, a click on the dock, the workspace switcher, the pane navigator or the command palette. These switches do not open a pane:

• move_and_follow and other moves that take a pane with them.
• tuios xpanes, tuios select-workspace, tuios run-command and tape scripts.
• The switch back that return_when_empty makes.
• The start of TUIOS and an attach to a session.

A workspace gets one pane, also when two clients switch to it at the same time. When you switch away before the pane opens, you stay where you went.

Each client reads the setting from its config file, and a change applies at once. The settings page lists it under Daemon, and tuios set-config workspaces.new_window_when_empty true changes it while TUIOS runs.

The daemon must be from the same release or newer. An older daemon opens no pane. Run tuios restart-server to load the new daemon.

The launcher table

The app launcher starts a desktop entry in a new pane. A graphical program opens its own window, so its pane stays empty. Set launcher.gui_command to start such an entry with another command. The launcher adds the entry's argv to that command. Entries with Terminal=true and programs from $PATH still open in a pane.

[launcher]
gui_command = "tuios-wayland launch --"   # or "niri msg action spawn --"

launcher.keep_open Added in v0.12.0 keeps the pane of a launched program open after it exits. A line under the output shows the exit status. The option needs a daemon session.

[launcher]
keep_open = true

The tape table

[tape] controls project tapes: a .tuios.tape file in a directory. See Tape Scripting.

A tape edited after you trusted it is untrusted again.

The debug table

--show-keys and Ctrl+B D k toggle the same overlay. See Showkeys.

The screenshot table

[screenshot] sets the defaults for tuios screenshot and the in-app capture (Ctrl+B C). Each key has a command flag that overrides it for one capture.

[screenshot]
format = "svg"
frame = "plain"
background = "none"
padding = 24

png and svg carry the frame. ansi and txt are plain output, so the frame keys do not apply.

The screensaver table

[screensaver] animates the screen after a period with no input. It is off by default.

[screensaver]
enabled = true
idle_minutes = 5
effect = "matrix"

There are 36 effects. tuios list-options screensaver.effect prints them. A plugin can add a saver Unreleased: set effect = "plugin/ID/SAVER". See A screen saver in a plugin. The settings page previews each effect on your current screen.

S in window mode starts the screen saver now, whatever enabled says.

The hints table

[hints] sets what hints mode (Ctrl+B F) labels.

See What hints mode finds for the pattern names.

The panes table

[panes] sets the keys of the pane labels (Ctrl+B Q) and the first layout of the pane navigator (Ctrl+B /).

With drag_and_drop on, a program that speaks the protocol, such as yazi 26.9 or later, can drag files from its pane. Hold the left button on a file in terminal mode, and carry it to another pane. A pane whose program speaks the protocol takes the drop itself. Any other pane gets the paths as a paste, quoted for its shell, by the rules of a drag from the rail. tuios reads no file, and refuses a drop back into the pane the drag came from. The switch is off because the protocol is still settling.

Drag and drop with the desktop Unreleased

Set drag_and_drop_desktop = true with drag_and_drop = true to drag files between the desktop and the panes. The terminal that tuios runs in must speak the same protocol. Today that is kitty 0.47 or later. tuios asks the terminal once at startup.

[panes]
drag_and_drop = true
drag_and_drop_desktop = true

• From the desktop: drag a file from a file manager or a browser onto the tuios window. It lands on the pane under the pointer. A program that speaks the protocol takes it. Any other pane gets the path as a paste, by the rules above.
• To the desktop: a file that a program in a pane drags, such as yazi, becomes a drag on the desktop. Drop it on any other window. The desktop shows the file names and the pane they come from.
• tuios takes a drag only when the press went to a pane that offers drags. You still move a pane, select text and drag a row of the rail as before.
• The bridge is for a terminal on this machine. A client over SSH, through tuios-web, or attached to the daemon of another machine does not use it.
• Both switches apply without a restart.

The path_picker table Added in v0.12.0

[path_picker] sets show_hidden. With true, the path picker shows the names that start with a dot when it opens. The default is false.

The worktree table Added in v0.12.0

[worktree] path sets where tuios worktree new, New worktree... on the rail and tuios fan put a worktree. The value is a path template. Empty is the default. See Where a worktree goes.

[worktree]
path = "{{ repo_path }}/.worktrees/{{ branch | slug }}"

The review table Added in v0.12.1

[review] sets how a review opens.

[review]
focus = "files"
scope = "uncommitted"

base shows the changes since the base. In a plain repository, the base is the merge base with the upstream branch, so commits that you did not push yet are part of the review. uncommitted shows only the changes that are not committed. In the review, u still switches between the two, and b still sets another base. The compare view of two attempts does not use scope.

Both keys are on the settings page, in the Behavior section. tuios set-config review.scope uncommitted applies from the next review. tuios reads another value as the default and shows a warning when the config loads. tuios set-config refuses it.

The tasks table Added in v0.12.0

[tasks] sets how the task board works.

[tasks]
stages = ["todo", "doing", "verify"]
auto_stage = false

The scratch table

[scratch] sets the size of the scratch terminal that Ctrl+B g shows in a popup. See Scratch terminal.

The old session key is no longer used. TUIOS ignores it, and the config warnings tell you to remove it.

The pip table

[pip] sets the size and the first corner of the picture-in-picture view. See Picture in picture.

The paste_buffers table

[paste_buffers] sets how many paste buffers the daemon keeps. The daemon reads it when it starts and when the file changes.

A smaller limit removes the oldest buffers at once. A yank larger than max_kb does not become a buffer, but it still goes to the clipboard.

Command keys

[[keybindings.command]] binds a key to a command that you write: a scratch terminal, a popup, a pane or a command with no window. A mistake in an entry is a warning, and TUIOS ignores that entry. See Command keys.

The spotlight table

[spotlight] lights one part of the screen and dims the rest, for screen sharing. B in window mode, or Ctrl+B B in any mode, turns it on and off. While it is on, Esc in window mode or a click on the Spotlight chip in the dock turns it off. See Spotlight.

follow = "cursor" sends fewer bytes to a remote client.

The dock table

[dock] sets what the bar draws: three ordered lists of component names, plus a table for each component that needs one. Edit it in the file, or with the Dock > Components editor on the settings page. set-config cannot change the lists.

[dock]
left   = ["mode", "workspaces", "trail", "tape"]
center = ["windows"]
right  = ["transfers", "notifications", "copy-help", "cpu", "ram", "clock", "session-controls"]

[dock.clock]
format = "15:04"

[dock.custom.branch]
command  = "git branch --show-current"
refresh  = "event:after-focus-change"
on-click = "tuios new-window log -- git log --oneline -20"

These lists are the default. A missing list uses the default. An empty list (left = []) draws nothing on that side.

The built-in components are mode, workspaces, trail, tape, windows, transfers, notifications, copy-help, cpu, ram, clock, session-controls and session. Listing one lets it draw. It still needs its own condition, so cpu still needs show_cpu. copy-help shows the keys of copy mode, multi copy mode and hints mode while the mode is open. See Mode keys in the dock.

transfers Added in v0.9.3 shows the copies between machines. It shows nothing while no copy exists. One copy is a bar and a percent, [####--] 61%. More copies are a count and a percent, 3 copies 42%. waiting means a link is down. 1 failed stays until you open the Copies panel. A click opens the Copies panel.

[dock.clock] takes format, a Go time layout. A layout without seconds refreshes once a minute.

Added in v0.10.0 session shows the session name, the workspace and the pane, such as main 2:1. It is in no default list. [dock.session] takes format, with {session}, {workspace} and {pane}. It also takes the cell style keys fg, bg, bold, cap_left and cap_right. [dock.custom.NAME] takes the same style keys. Colours are #rrggbb.

Added in v0.10.0 When the center list has a clock or a custom cell, the centre is at the middle of the terminal. A notification does not move it, and it does not shorten the minimized pane labels. On a crowded bar, the centre moves left to keep the cells on the right on the screen. Click a cut notification to read the full message.

Custom components

[dock.custom.NAME] defines a cell. Put custom/NAME in a list to place it.

With push, the command keeps running and each line it prints replaces the cell. With event:, the command runs again when the daemon reports one of those hook events.

A component whose command fails is hidden. tuios list-dock-components shows what each component last did and why a cell is missing. tuios refresh-dock [name] runs a component again now.

A command runs in the client, with a three second timeout. TUIOS reads at most 64 KiB of its output and stops the command when it prints more. SGR colour stays. TUIOS removes other control sequences, C1 controls, bidirectional and invisible characters, and bytes that are not UTF-8. Wide characters and emoji stay.

SSH server limits Added in v0.12.0

The [ssh] table sets the limits of the tuios ssh server. The server reads it when it starts. The defaults do not stop a normal login.

[ssh]
handshake_timeout = "120s" # time to finish the login; 0 turns the limit off
idle_timeout = "0"         # close a connection with no traffic for this long; 0 is off
max_handshakes = 32        # connections that log in at the same time; 0 is no limit
max_sessions = 64          # sessions open at the same time; 0 is no limit

A duration is a value such as 90s, 30m or 2h. A value that does not parse, or a negative value, gives a warning and the default. tuios ssh --handshake-timeout, --idle-timeout, --max-handshakes and --max-sessions replace these values for one run. The server writes the limits it uses to its log when it starts. tuios set-config cannot change this table.

The hosts table

[hosts] names the other machines this daemon links to. Each host is a table.

[hosts.build]
addr = "gaurav@buildbox"

[hosts.work]
addr = "workstation"
connect_timeout = 5

You can also manage the table from the shell. These commands edit the file:

tuios hosts add build gaurav@buildbox
tuios hosts test build
tuios hosts remove build

A change that gives a machine less applies at once, also on links that are open. A new host, a host that dials another way, or a change that gives a machine more waits for tuios config apply from a terminal outside TUIOS. A daemon restart also applies it. So tuios hosts add from a pane waits. A host that you add with "Add a host" on the settings page applies at once. See Changes that wait.

Rules for ssh_options

ssh_options accepts only options that cannot run code or write files on this machine. Write each option as -o Keyword=value, with one plain value and no quotes.

• Accepted examples: -p, -i, -l, -J, Port, User, HostName, HostKeyAlias, IdentityFile, StrictHostKeyChecking, the ServerAlive options and the algorithm lists.
• Refused: ProxyCommand, LocalCommand, the known hosts files, ControlPath, -F and socket forwards.
• Refused: port forwards (-L, -R, -D).
• -J and ProxyJump take host names only. ForwardAgent takes only yes or no.
• A host addr or command cannot start with a dash.

TUIOS drops a host with a refused option. tuios hosts and the Inbox name the reason. Put a refused option in ~/.ssh/config, and name that host in addr.

[hosts.build]
addr = "gaurav@buildbox"
ssh_options = ["-J", "bastion", "-o", "ServerAliveInterval=30"]

The daemon runs ssh with BatchMode on, so a link never asks for a password or about a host key. Run ssh to the host once by hand to accept its key.

What another machine may do here

The same [hosts.NAME] table, read on the machine a link arrives at, also says what the machine of that name may do there. [hosts."*"] covers every machine with no table of its own.

[hosts.laptop]
addr = "laptop"                  # optional: without it nothing is dialled
allow = ["list", "mail", "open", "write", "respond"]
hold_mail = true
hosted_grace = "10m"

[hosts."*"]
allow = ["list", "mail"]

list also lets the other machine stream the bytes of a pane (stream-pane). Added in v0.9.3

With no table, a machine may list, mail, open, write and files. respond is opt-in. An allow that is set replaces that list, and allow = [] allows nothing. A table that sets allow without files keeps that machine from your files. Anything not allowed is refused with forbidden.

To relay on to this machine's own hosts, a machine needs list, mail, open, write and respond. A table written for an older tuios that allows those five still relays.

hold_mail = true holds mail from that machine to an agent here in your Inbox, marked held for NAME, until you pass it on with p. hosted_grace is how long a pane this machine runs for the other one (a window opened there with --host) keeps running after the link drops: a duration, "0" to end it with the link, 10 minutes when unset, at most 24 hours.

The name is the one the other machine gives for itself, its host name up to the first dot, unless the ssh key it logs in with pins one with command="tuios stdio-proxy --as laptop",restrict. Only a pinned name is a boundary. A change that allows less applies to the next call on every link. A change that allows more waits for tuios config apply.

Files over a link Added in v0.9.3

A machine with files can read your files and write new ones. Three keys in its [hosts.NAME] table set the limits:

[hosts.laptop]
allow = ["list", "files"]
files_roots = ["~/Downloads/tuios", "~/dev"]   # where it may write
files_read_roots = ["~/share"]                 # where it may read
files_min_free = "5GiB"                        # the space a write must leave free

A path is absolute or starts with ~. Some places are always closed, whatever the roots say:

• Writes never go into ~/.ssh, ~/.gnupg, cloud and git credentials, shell start files such as .bashrc and .zshrc, login items, crontabs, /proc, or tuios's own config and state.
• Reads never return keys, credentials, keyrings, shell histories, browser profiles, /proc, or tuios's own state. A public *.pub key in ~/.ssh is the one exception.
• Reads also never return ~/.gitconfig, ~/.config/git, shell start files or ~/.config/environment.d. The list also covers the snap and flatpak browser folders, Thunderbird, Signal, Discord, Slack, Telegram, VS Code and common crypto wallets. A folder copy over a link leaves these entries out.
• A file with more than one name (a hard link) is never read over a link. Copy it to a new file to share it.

The read rules and files_read_roots also apply to a kitty image that a program names by path in a pane that runs on this machine for the other machine. See Kitty images in the pane.

A refused write says where writes may land and which key to change. A deny list can never name every secret on a machine, so files_read_roots is the stronger choice.

Other limits:

• One machine may have at most 8 write streams and 64 unfinished copies here at once. Past that, a write is busy, and a copy waits and tries again.
• Files dropped on a pane go to a private drop folder. It holds at most 256 MiB for all drops, for 24 hours.
• A copy another machine starts here keeps to the same rules, also after tuios restarts. When files is taken away, its copies here stop.
• A change that widens files_roots or files_read_roots, removes files_read_roots, or lowers files_min_free waits for tuios config apply. A change that narrows applies at once.
• A file that another machine writes here gets the sender's permission bits under this machine's umask. It never gets group or world write. The execute bits stay. This holds for a paired device too.
• A machine with files cannot write the config folders of the agent tools that tuios integrates. It also cannot read the logins and API keys of more agent tools and cloud tools.

See Remote Hosts for the copies themselves.

Using a linked host

Once a host is linked, you can list its sessions and agents (tuios ls --all-hosts, tuios list-agents --host build), attach to or create sessions on it (tuios attach --host build api, tuios new --host build), and open a pane whose process runs there (tuios new-window --host build). See tuios hosts.

Reaching a host you cannot ssh to directly

A host behind NAT, with no port forward and no jump host, is a network problem to solve under TUIOS. Any tool that pipes stdio to a remote port works as an ssh ProxyCommand. ssh_options refuses ProxyCommand, so name it in ~/.ssh/config.

Tailscale's tailcat is one such tool. It carries a connection over WireGuard with no Tailscale account and no open port. Run it on the far side against sshd:

tailcat --serve=22

Then add a host to ~/.ssh/config that uses it:

Host laptop-tailcat
    HostName laptop
    User gaurav
    ProxyCommand tailcat <token> 22

Name that host in the host entry:

[hosts.laptop]
addr = "laptop-tailcat"

ssh still decides who may connect: the tunnel only carries bytes to sshd, which asks for your key as usual. A leaked tailcat token gives reachability, not access. TUIOS adds no identity system of its own and opens no listening port.

The tailscale table

[tailscale] changes which tailnet machines tuios hosts add and tuios hosts tailnet offer as addresses. It never adds a host by itself.

[tailscale]
user = "ubuntu"
exclude = ["*-pad-*"]

[tailscale.users]
build = "admin"

The agents table

[agents] sets how TUIOS treats the coding agents in its panes. Except for enabled, it is outside list-options, and set-config cannot change it, so a program in a pane cannot loosen it. The daemon reads it at start and again whenever the file changes. See Inbox and Review for what each part does.

Turn off agent features

[agents]
enabled = false

enabled (default true) is the one switch for every agent feature. With it off, TUIOS is only a multiplexer: no agent detection, no agents section on the rail, no Inbox, mail, approvals or agent alerts, and agent commands stop with a message. The change applies at once. It is the first row of the settings page, "Agent features", and tuios set-config agents.enabled false from a shell outside TUIOS also sets it. A process in a pane cannot change it. See Turn Off Agent Features.

Agents that stop reporting Added in v0.12.0

A hooked agent reports at each prompt and each tool call. When an agent that reported working sends no report for silent_after, tuios shows it as unknown with the reason silent. Its row reads "No report for N min".

[agents]
silent_after = "10m"   # default; "0" or "off" turns it off

The value is a Go duration, such as 90s or 20m. A value that does not parse reads as 10m, with a warning. The daemon reads the value when it starts and when the file changes. See Agents that stop reporting.

Fold the Working group Added in v0.12.0

fold_working = true opens the agents view with the Working group folded. A folded group shows its heading, its count and the state mark of each agent. F folds or opens any group. tuios keeps that choice in sidebar.json in its state folder, and the choice wins over fold_working. The settings page has this option as "Fold Working".

The other agent tables

[agents.approvals]
enabled = ["claude-code", "opencode"]   # harnesses whose permission prompts the Inbox may answer
hold_seconds = 120                      # 10 to 300
hold_plans = true                       # a plan follows enabled

[agents.approvals.risk]
builtin = true                          # keep the shipped risk rules
panes_may_allow = false                 # a pane with the respond grant may not allow a risky call

[[agents.approvals.risk.rule]]
name = "kubectl apply"
tools = ["Bash"]                        # empty: every tool
pattern = '\bkubectl\s+(apply|delete)\b'   # RE2, matched per command

[agents.permissions]
mode = "strict"                         # open (default) or strict
grants = ["read", "write", "fan"]       # what a pane holds under strict

[agents.recap]
mode = "toast"                          # toast, inbox or off
away = "10m"
test_patterns = ["go test", "pytest"]

[agents.queue]
max = 8                                 # at most 64

[agents.mail]
wake = true                             # type one line into an idle agent with unread mail

[agents.checkpoints]
enabled = true
keep = 50                               # at most 1000
max_untracked_mb = 50                   # a negative value means no limit

After turning on approvals.enabled, run tuios integration install for that harness again, so its hook is the version that waits. The grants are read, write, fan, respond, files and admin. See What a pane may do.

A change to [agents.permissions] that gives panes less applies at once. A change that gives more, such as strict to open, waits. Run tuios config apply from a terminal outside TUIOS, or restart the daemon. See Changes that wait.

The notify table

[notify] sends a push notification when the Inbox gets an item that waits for you. The daemon sends it, so it works when no client is attached. The providers are ntfy, Pushover and a webhook.

[notify]
web_url = "https://term.example.com/"   # tuios-web, for a link to the item

[notify.ntfy]
url = "https://ntfy.sh/a-long-random-topic"
token_file = "~/.config/tuios/ntfy-token"   # optional

[notify.triggers] selects the Inbox kinds: approval, plan, question and ask are on by default, mail, errored and finished are off. Like [hosts], [notify] is not in list-options, and tuios set-config cannot change it. A new address or a new source for a secret waits for tuios config apply from a terminal outside TUIOS. tuios notify test sends a test notification through each provider. See Push Notifications for the providers and the secrets.

Web Push Added in v0.9.3

[notify.webpush] configures the pushes the daemon sends to a phone that registered for Web Push. It needs no provider.

[notify.webpush]
subject = "https://example.com/tuios-contact"   # optional
allow_insecure = false

See Push Notifications.

Hooks

[hooks] runs shell commands on window, workspace, session and agent events. Event names use hyphens, such as after-new-window. See Hooks and tuios list-hooks.

Validation

The file is checked when it loads. Problems are errors or warnings.

Errors are keys TUIOS cannot read, such as "ctrl+nope" or "ctrl+". TUIOS ignores each of these keys and loads the rest of the file. See When a key is wrong.

Warnings keep the key. They cover unknown values (which fall back to the default), unknown title placeholders, actions with no key, two actions on one key in the same section, and the macOS alt+ advice.

TUIOS shows the number of problems when it starts, for example 2 config problems, see the log viewer. The log viewer (leader D l) shows each problem.

When a key is wrong

TUIOS ignores a key that it cannot read, such as ctrl+nope. It loads the rest of the file. Your other keys, the leader and the other settings stay as you wrote them.

The action of an ignored key gets a key as follows:

• If the action has another key that TUIOS can read, the action keeps that key.
• If the action has no other key, it gets its default key.
• If another action already has that default key, the action has no key.
• If TUIOS cannot read leader_key, the leader is ctrl+b until you correct it.

TUIOS does not change your file. Correct the key, then save. The change applies at once.

To find the ignored keys:

• Look for the config problems notification when TUIOS starts.
• Open the log viewer (leader D l). Each line names the key and its file.
• Run tuios keybinds doctor. It lists each key by file and says what TUIOS does instead. See Keybindings.
• Run tuios config apply. It lists the keys it ignored.

The same rule applies to keys in an included file and in config.d.

One config on macOS and Linux

You can use one config.toml on a Mac and on a Linux machine, for example from a dotfiles repo. TUIOS reads opt+ and option+ as alt+ on every platform. On Linux, opt+1 is alt+1.

[keybindings.workspaces]
switch_workspace_1 = ["opt+1"]   # Option+1 on macOS, Alt+1 on Linux

tuios keybinds doctor lists these keys under OPT KEYS READ AS ALT. This is for information. You do not need to change them.

Troubleshooting

My config seems ignored.

1. Run tuios config path to confirm which file TUIOS reads. Run tuios config files to see every file that TUIOS reads.
2. Look for the config problems notification when TUIOS starts. Open the log viewer (leader D l) to see each problem.
3. Run tuios keybinds doctor. It lists each key that TUIOS cannot read, and the leader that TUIOS uses. TUIOS ignores only those keys. See When a key is wrong.
4. If the log says the file does not parse, correct the TOML. TUIOS uses the defaults until then.
5. On Linux, a key copied from a Mac works. opt+ is alt+ on every platform.

A setting changed nothing.

1. Check the table of what applies live. A saved keybinding works at the next key press.
2. Check that the file parsed. Look for an error notification, or run tuios keybinds list.
3. Check whether a command-line flag is overriding it.
4. Check whether a later file sets the key. Run tuios config origin <key>. An old config.toml that sets every key hides the other files. Run tuios config prune to remove its default values. See Split the Config.
5. For a hook, check the event name spelling with tuios list-hooks.

A key does nothing. Run tuios keybinds explain <key> to see every place it is bound, and tuios keybinds doctor for conflicts.

Examples

Browser-style keys

[keybindings.window_management]
new_window = ["ctrl+t"]
close_window = ["ctrl+w"]
next_window = ["ctrl+tab"]
prev_window = ["ctrl+shift+tab"]

Screen-style leader

[keybindings]
leader_key = "ctrl+a"

[keybindings.prefix_mode]
prefix_new_window = ["c"]
prefix_split_horizontal = ["S"]
prefix_split_vertical = ["V"]
prefix_session_switcher = ["s"]
prefix_scrollback = ["/"]

In this example, S and s are taken by the splits and the switcher, so the scrollback browser moves to /. Keys inside one section must not collide.

A quiet, dense layout

[appearance]
theme = "nord"
border_style = "hidden"
dockbar_position = "hidden"
shared_borders = true
whichkey_enabled = false
window_title_format = "{index}: {title}"
scrollback_lines = 50000
max_fps = 120

Related