# Option Reference

URL: https://tuios.dev/docs/option-reference

> Every option of the TUIOS config.toml with its type, default and description, written from the option registry.

This page is `docs/config-options.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/config-options.md), at the version this site documents.

To filter the options by name, type or value, use the [option explorer](https://tuios.dev/docs/config-options).

Each option is a key in `config.toml`. `tuios set-config` and the settings page change the same options.
[CONFIGURATION.md](https://tuios.dev/docs/configuration) tells more about the options that need it.
The defaults are the ones on Linux. Some defaults are different on macOS.

## agents

| Option                         | Type   | Default  | Description                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents.acp_version`           | int    | `0`      | The ACP version a pane start-agent --protocol acp opens asks the agent for: 1, or 2, a draft of the spec. An agent that speaks only version 1 still works when 2 is asked for. The daemon reads it when it starts a protocol pane Range: 1 to 2.                                                              |
| `agents.answer_advance`        | bool   | `true`   | After an answer in the agents view, move the cursor to the next agent that needs you. Off keeps the cursor on the agent you answered.                                                                                                                                                                         |
| `agents.ask_wait_seconds`      | int    | `120`    | Seconds ask-human waits for your answer when the agent names no timeout. The question stays after the wait. 0 uses 120 Range: 0 to 3600.                                                                                                                                                                      |
| `agents.card_preview`          | string | `auto`   | Where the task board shows the focused card's preview: beside the columns, over them, beside them on a wide screen and over them otherwise, or never. Space on a card opens and closes it. Values: `auto`, `side`, `sheet`, `off`.                                                                            |
| `agents.card_preview_width`    | string | empty    | The width of the task board's preview panel: a number of cells, such as 70, or a share of the view, such as 40%. Empty is 40%, at least 44 and at most 96 cells. A drag on the edge of the panel changes it, and the view keeps that choice.                                                                  |
| `agents.enabled`               | bool   | `true`   | Agents, the Inbox, mail and approvals. Turn off to keep only the multiplexer.                                                                                                                                                                                                                                 |
| `agents.fold_working`          | bool   | `false`  | Fold the Working group of the agents view. F folds or opens a group, and the view keeps that choice.                                                                                                                                                                                                          |
| `agents.list_width`            | string | empty    | The width of the agents view's list: a number of cells, such as 52, or a share of the view, such as 30%. Empty follows the screen. The < and > keys and a drag on the edge of the list change it, and the view keeps that choice.                                                                             |
| `agents.name_hint`             | string | `on`     | Whether the start hint tells an agent to name its pane after its task. Off leaves that line out and tells the agent not to rename its pane or its session, so the title the program sets and the session's label stay as they are. A running agent keeps the hint it got at its start. Values: `on`, `off`.   |
| `agents.reply_markers`         | bool   | `false`  | Ask the agents that start-agent starts to write reply markers, such as \[\[Done]] and \[\[Failed: 3 tests]]. The agents view shows each marker as a coloured label. It applies to Claude Code, which takes an added system prompt.                                                                            |
| `agents.reply_rows`            | int    | `0`      | The most rows a multi-line editor grows to before it scrolls: a reply to an agent or to many, a mail draft and a new agent's task. 0 keeps each editor's own: 8 for a reply, 6 for mail, 3 for a task. An editor never takes more rows than its view has, and alt+m in it takes all of them. Range: 0 to 200. |
| `agents.undo_window_seconds`   | int    | `10`     | Seconds after a dismiss, a snooze or a queued reply that u takes it back. 0 uses 10 Range: 0 to 300.                                                                                                                                                                                                          |
| `agents.view_list`             | string | `column` | How the agents view shows its list on a wide screen: a column beside the focus, a strip of chips above it, or a strip for two agents or fewer. The \ key switches it, and the view keeps that choice. Values: `column`, `strip`, `auto`.                                                                      |
| `tasks.attachment_max_mib`     | int    | `8`      | The largest file that tuios task attach puts on a card. A larger file is refused with an error that names this option. 0 uses 8 Range: 0 to 8.                                                                                                                                                                |
| `tasks.attachment_session_mib` | int    | `256`    | The most that the files on one session's task cards take together. 0 uses 256 Range: 0 to 65536.                                                                                                                                                                                                              |
| `tasks.attachments_per_card`   | int    | `20`     | The most attachments one task card holds. 0 uses 20 Range: 0 to 200.                                                                                                                                                                                                                                          |
| `tasks.auto_stage`             | bool   | `true`   | Move task cards on their own when tuios sees their work move: a plan held and then approved, a fan check, a pull request. Off leaves every stage to you.                                                                                                                                                      |
| `tasks.machine_cap`            | int    | `0`      | How many agents may work on this machine before Any machine starts a new one on another machine. Agents that work, agents that start, and picks not yet started count. 0 is no cap. Range: 0 to 1024.                                                                                                         |

## appearance

| Option                                     | Type   | Default        | Description                                                                                                                                                                                                                                                                                       |
| ------------------------------------------ | ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance.alt_drag`                      | bool   | `true`         | Alt plus left-drag moves a pane                                                                                                                                                                                                                                                                   |
| `appearance.animation_speed`               | int    | `100`          | Percent window animations run at: 100 as shipped, 200 twice as fast, 50 half as fast Range: 25 to 400.                                                                                                                                                                                            |
| `appearance.animations_enabled`            | bool   | `true`         | Animate UI transitions instead of applying them instantly Deprecated: folded into appearance.motion on load (false is none); set appearance.motion                                                                                                                                                |
| `appearance.auto_enter_terminal_on_focus`  | string | `off`          | Type in a pane when a keyboard focus command moves to it: off, targeted (select and arrows), or all (including Tab) Values: `off`, `targeted`, `all`.                                                                                                                                             |
| `appearance.background`                    | string | `off`          | Background painted on every surface not set on its own (panes, desktop, window chrome, dock, rail): off (your terminal shows through), theme, or a colour (#rrggbb, 0-255, a slot name or a role name)                                                                                            |
| `appearance.border_focused_color`          | string | empty          | Colour overriding the focused pane's border in both modes: #89b4fa, a slot name such as bright\_cyan, or a role such as accent                                                                                                                                                                    |
| `appearance.border_focused_color_terminal` | string | empty          | Colour of the focused pane's border in terminal mode. It wins over border\_focused\_color                                                                                                                                                                                                         |
| `appearance.border_focused_color_window`   | string | empty          | Colour of the focused pane's border in window mode. It wins over border\_focused\_color                                                                                                                                                                                                           |
| `appearance.border_focused_gradient`       | string | empty          | Two or more colours, separated by spaces or commas, that the focused pane's border steps through. Empty draws one colour                                                                                                                                                                          |
| `appearance.border_gradient_angle`         | int    | `45`           | Direction of the focused border's gradient in degrees: 0 runs left to right, 90 top to bottom, 45 from the top left corner to the bottom right one Range: 0 to 359.                                                                                                                               |
| `appearance.border_style`                  | string | `rounded`      | Border style drawn around every pane Values: `rounded`, `normal`, `thick`, `double`, `block`, `outer-half-block`, `inner-half-block`, `ascii`, `hidden`, `glyphs`. `--border-style` sets it for one run.                                                                                          |
| `appearance.border_unfocused_color`        | string | empty          | Colour overriding an unfocused pane's border: #585b70, a slot name such as bright\_black, or a role such as muted                                                                                                                                                                                 |
| `appearance.calm`                          | bool   | `false`        | Calm mode: nothing moves or blinks, and only messages that need you show in the dock                                                                                                                                                                                                              |
| `appearance.cell_frames`                   | string | `all`          | Which clients write their frames as diffed cells instead of through Bubble Tea's renderer, which turns each frame into text and back. served: clients over SSH and the web. all: this terminal as well. off: none. TUIOS\_CELL\_FRAME=1 means all and 0 means off Values: `served`, `all`, `off`. |
| `appearance.chord_timeout_ms`              | int    | `500`          | Milliseconds the first key of a two-key chord (gg in copy mode and the scrollback browser) waits for the second Range: 100 to 3000.                                                                                                                                                               |
| `appearance.click_to_type`                 | string | `double`       | What a click on a pane's content does in window-management mode Values: `single`, `double`, `off`.                                                                                                                                                                                                |
| `appearance.confirm_close`                 | string | `never`        | When closing a pane by hand (a key, its menu or its close control) asks first: never, busy (the pane runs something besides its shell) or always Values: `never`, `busy`, `always`.                                                                                                               |
| `appearance.confirm_quit`                  | bool   | `false`        | Always confirm on quit, not only when processes are running `--confirm-quit` sets it for one run.                                                                                                                                                                                                 |
| `appearance.copy_on_select`                | bool   | `true`         | Copy a mouse selection to the clipboard on release                                                                                                                                                                                                                                                |
| `appearance.copy_search_max_matches`       | int    | `1000`         | Matches one copy mode search keeps. The renderer walks every match on every frame, so a very high value slows a one-letter query over a long scrollback. A search that stops at the limit shows 1000+. Range: 100 to 100000.                                                                      |
| `appearance.desktop_background`            | string | empty          | Background behind and between panes: the gaps between tiled panes, the space around floating ones, and an empty workspace with its welcome splash. off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background                                      |
| `appearance.dim_foreground`                | bool   | `true`         | Let dim\_unfocused dim a pane's text too, not only its background                                                                                                                                                                                                                                 |
| `appearance.dim_multifocus`                | bool   | `false`        | Dim the panes in the multifocus set like other panes you are not in                                                                                                                                                                                                                               |
| `appearance.dim_unfocused`                 | int    | `0`            | How much tuios fades a pane you are not in, as a percent. 0 is off. Range: 0 to 90.                                                                                                                                                                                                               |
| `appearance.drop_preview`                  | string | `outline`      | What a BSP drag shows where the pane would land: a frame with a tint inside, the frame only, or nothing Values: `fill`, `outline`, `off`.                                                                                                                                                         |
| `appearance.drop_preview_delay`            | string | `120ms`        | How long the pointer rests on a drop zone before it shows: a duration such as 120ms, or 0 for at once. A zone you leave before the delay is never drawn                                                                                                                                           |
| `appearance.focus_follows_mouse`           | bool   | `false`        | Focus the pane under the cursor as the mouse moves                                                                                                                                                                                                                                                |
| `appearance.focus_follows_mouse_pause`     | string | `off`          | Hold this key to keep the focus on the current pane as the mouse moves: off, ctrl, alt Values: `off`, `ctrl`, `alt`.                                                                                                                                                                              |
| `appearance.focus_wrap`                    | bool   | `false`        | A focus key at the edge of a tiled layout moves to the pane on the far side                                                                                                                                                                                                                       |
| `appearance.frame_panels`                  | bool   | `false`        | Frame the larger overlay panels, such as the command palette, in the border style                                                                                                                                                                                                                 |
| `appearance.gap`                           | int    | `0`            | Cells of empty ground kept between two neighbouring tiled panes Range: 0 to 8.                                                                                                                                                                                                                    |
| `appearance.global_session`                | bool   | `true`         | Offer a session in the rail that holds panes from several machines, once a second one is reachable                                                                                                                                                                                                |
| `appearance.glyphs`                        | string | `default`      | Chrome glyph set: the characters the border, controls, rules and rail marks are drawn with                                                                                                                                                                                                        |
| `appearance.hide_scrollbar`                | bool   | `false`        | Hide the scrollbar thumb on the pane border `--hide-scrollbar` sets it for one run.                                                                                                                                                                                                               |
| `appearance.hide_window_buttons`           | bool   | `false`        | Hide the minimize, maximize and close buttons `--hide-window-buttons` sets it for one run.                                                                                                                                                                                                        |
| `appearance.host_title`                    | string | empty          | Title of the terminal tuios runs in, from the focused pane: accepts {title}, {index}, {cwd}, {session} and {workspace}. Empty sets no title                                                                                                                                                       |
| `appearance.idle_fps`                      | int    | `10`           | Polls per second while nothing is moving. Lower saves power; higher notices background work sooner. appearance.max\_fps sets the rate while something moves. Range: 1 to 60.                                                                                                                      |
| `appearance.image_symbols`                 | string | `auto`         | Draw pane images as block glyphs when the terminal has no graphics: auto, octant, sextant, quadrant, half, off Values: `auto`, `octant`, `sextant`, `quadrant`, `half`, `off`.                                                                                                                    |
| `appearance.kitty_placeholders`            | string | `auto`         | Draw images an app positions with kitty Unicode placeholders: auto, on, off Values: `auto`, `on`, `off`.                                                                                                                                                                                          |
| `appearance.link_click`                    | string | `both`         | The click that opens a link: ctrl or shift, ctrl only, shift only, or none. Ctrl+click also works on macOS in Ghostty, kitty, WezTerm and Terminal.app. Cmd+click does not open a link there Values: `both`, `ctrl`, `shift`, `off`.                                                              |
| `appearance.link_hover`                    | string | `safe`         | The hover highlight: safe skips a pane whose guest tracks the mouse, always draws it everywhere Values: `safe`, `always`.                                                                                                                                                                         |
| `appearance.link_opener`                   | string | empty          | The command that opens a web link. tuios puts the URL where %s is, or at the end. If this is empty, tuios uses $BROWSER, then the system opener.                                                                                                                                                  |
| `appearance.links`                         | string | `all`          | Links the pointer picks up: off, only marked links (OSC 8), or plain URLs too Values: `off`, `marked`, `all`.                                                                                                                                                                                     |
| `appearance.master_count`                  | int    | `1`            | How many panes are master panes in the master-stack layout Range: 1 to 9.                                                                                                                                                                                                                         |
| `appearance.master_grid`                   | bool   | `true`         | With one master on the left, show four or more panes as a grid                                                                                                                                                                                                                                    |
| `appearance.master_position`               | string | `left`         | Side the master panes take in the master-stack layout. With center, the stack panes go to the right and the left in turn. Values: `left`, `right`, `top`, `bottom`, `center`.                                                                                                                     |
| `appearance.master_ratio`                  | int    | `50`           | Width of the master pane in the master-stack layout, as a percent of the screen Range: 10 to 90.                                                                                                                                                                                                  |
| `appearance.max_fps`                       | int    | `0`            | Highest frame rate tuios draws at. Your terminal and monitor can show fewer frames. A value above what they can show does not make tuios smoother. 0 uses 60. auto uses the refresh rate of your display. The range is 10 to 240. Range: 0 to 240.                                                |
| `appearance.modal_dim`                     | int    | `30`           | How much the screen behind a modal panel is darkened, as a percent. 0 is off. Range: 0 to 90.                                                                                                                                                                                                     |
| `appearance.motion`                        | string | `full`         | How much moves: none, basic (window slides, workspace slides and the copy sweep), or full (also overlay fades and the working-agent shimmer) Values: `none`, `basic`, `full`.                                                                                                                     |
| `appearance.multi_copy_dim`                | int    | `45`           | Percent a pane is dimmed when multi copy mode's search found nothing in it. 0 leaves it undimmed. Range: 0 to 90.                                                                                                                                                                                 |
| `appearance.new_window_follow_ssh`         | bool   | `false`        | A split or new window of a pane that runs ssh runs the same ssh                                                                                                                                                                                                                                   |
| `appearance.new_window_inherit_cwd`        | bool   | `true`         | A new window starts in the focused pane's working directory                                                                                                                                                                                                                                       |
| `appearance.niri_click_reveals`            | bool   | `true`         | In the scrolling layout, clicking a column that is partly off the edge brings all of it on screen                                                                                                                                                                                                 |
| `appearance.niri_hover_reveals`            | bool   | `true`         | In the scrolling layout with focus-follows-mouse on, hovering a column that is partly off the edge brings all of it on screen                                                                                                                                                                     |
| `appearance.niri_reverse_scroll`           | bool   | `false`        | Reverse the wheel direction in niri scrolling mode                                                                                                                                                                                                                                                |
| `appearance.niri_scroll_cells`             | int    | `8`            | Cells the scrolling layout's strip moves per mouse wheel event Range: 1 to 200.                                                                                                                                                                                                                   |
| `appearance.niri_scroll_snap`              | bool   | `false`        | Snap the strip to the nearest column when a scroll stops                                                                                                                                                                                                                                          |
| `appearance.nvim_navigation`               | bool   | `false`        | Let the Neovim navigator plugin hand terminal focus keys back to TUIOS                                                                                                                                                                                                                            |
| `appearance.overlay_border_color`          | string | empty          | Colour of every overlay's frame: #89b4fa, a slot name such as bright\_cyan, or a role such as accent. Empty keeps the overlay's own, or the focused pane's border under pane\_overlays                                                                                                            |
| `appearance.pane_background`               | string | empty          | Background behind pane content, the thin scrollbar over it and the scrollback browser: off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background                                                                                                  |
| `appearance.pane_overlays`                 | bool   | `false`        | Draw dialogs and panels like pane windows: framed in the focused pane's border colour, on the pane's background                                                                                                                                                                                   |
| `appearance.panel_padding`                 | int    | `2`            | Columns of padding each side of an overlay panel's content Range: 1 to 6.                                                                                                                                                                                                                         |
| `appearance.paste_preview`                 | bool   | `true`         | Show a pasted image in a card at the cursor for a few seconds                                                                                                                                                                                                                                     |
| `appearance.paste_preview_ms`              | int    | `6000`         | Milliseconds the paste card stays up with nothing pressed Range: 500 to 60000.                                                                                                                                                                                                                    |
| `appearance.popup_dim`                     | int    | `0`            | How much the screen behind a focused plain popup is darkened, as a percent. 0 is off; popup --dim overrides it. Range: 0 to 90.                                                                                                                                                                   |
| `appearance.preferred_shell`               | string | empty          | Shell that new panes run. Empty picks one for your platform.                                                                                                                                                                                                                                      |
| `appearance.prefix_repeat_time`            | int    | `500`          | Milliseconds the prefix stays armed after a repeatable command. 0 turns it off. Range: 0 to 5000.                                                                                                                                                                                                 |
| `appearance.right_click_opens_menu`        | bool   | `false`        | A plain right-click on a pane in terminal mode opens the pane menu, for pasting without selecting first                                                                                                                                                                                           |
| `appearance.scroll_column_max`             | int    | `90`           | Highest a column's width may be set to in the scrolling layout, as a percent. 100 lets a column fill the screen, at the cost of the next one peeking in at the edge. Range: 20 to 100.                                                                                                            |
| `appearance.scroll_column_width`           | int    | `55`           | Width of a column in the scrolling layout, as a percent of the screen Range: 20 to 100.                                                                                                                                                                                                           |
| `appearance.scroll_lines`                  | int    | `3`            | Lines scrolled per mouse wheel notch Range: 1 to 50.                                                                                                                                                                                                                                              |
| `appearance.scrollback_lines`              | int    | `10000`        | Lines each pane keeps in its scrollback. A pane takes the value when it is made. The daemon reads it when it starts Range: 100 to 1000000. `--scrollback-lines` sets it for one run.                                                                                                              |
| `appearance.session_border`                | bool   | `false`        | Carry the session's colour on every pane border, not only on the rail                                                                                                                                                                                                                             |
| `appearance.session_colors`                | bool   | `true`         | Give each session its own colour on the rail and in the switcher                                                                                                                                                                                                                                  |
| `appearance.shared_borders`                | bool   | `false`        | Draw one border between neighbouring tiled panes, in every layout `--shared-borders` sets it for one run.                                                                                                                                                                                         |
| `appearance.sidebar_enabled`               | bool   | `false`        | Show the session rail Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.enabled                                                                                                                                                                                       |
| `appearance.sidebar_position`              | string | empty          | Edge the session rail sits on Values: `left`, `right`, `hidden`. Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.position                                                                                                                                           |
| `appearance.sidebar_show_counts`           | bool   | `true`         | Show the window count on each session row Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.show\_counts                                                                                                                                                              |
| `appearance.sidebar_show_glyphs`           | bool   | `true`         | Show the agent-state glyph on each rail row Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.show\_glyphs                                                                                                                                                            |
| `appearance.sidebar_show_windows`          | bool   | `true`         | Show the terminals section on the rail Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.show\_windows                                                                                                                                                                |
| `appearance.sidebar_width`                 | int    | `0`            | Preferred rail width in columns Deprecated: folded into \[appearance.sidebar] on load; set appearance.sidebar.width                                                                                                                                                                               |
| `appearance.theme`                         | string | empty          | Colour theme name. Empty follows Omarchy when it is installed, else keeps your terminal's colours. none always keeps them.                                                                                                                                                                        |
| `appearance.theme_light`                   | string | empty          | Theme to use while the terminal is light. Empty uses theme for both. theme is then the dark theme                                                                                                                                                                                                 |
| `appearance.theme_transition`              | string | `none`         | How tuios shows a theme change: none, circle (the new theme grows from the middle of the screen) or fade Values: `none`, `circle`, `fade`.                                                                                                                                                        |
| `appearance.theme_transition_duration`     | int    | `450`          | Milliseconds a theme transition takes at animation speed 100 Range: 100 to 2000.                                                                                                                                                                                                                  |
| `appearance.tiling_scheme`                 | string | `spiral`       | BSP scheme a workspace inserts new windows with the first time it is tiled. A workspace already tiled keeps its own scheme. Values: `spiral`, `longest_side`, `alternate`, `smart_split`.                                                                                                         |
| `appearance.tooltip_delay_ms`              | int    | `350`          | Milliseconds the pointer rests on a control before its tooltip shows. 0 shows it at once. Range: 0 to 5000.                                                                                                                                                                                       |
| `appearance.whichkey_delay_ms`             | int    | `500`          | Milliseconds after the leader key before the which-key panel opens. 0 opens it at once. Range: 0 to 5000.                                                                                                                                                                                         |
| `appearance.whichkey_enabled`              | bool   | `true`         | Show the which-key popup after the leader key                                                                                                                                                                                                                                                     |
| `appearance.whichkey_position`             | string | empty          | Corner the which-key popup opens in (empty: bottom-right) Values: `bottom-right`, `bottom-left`, `top-right`, `top-left`, `center`.                                                                                                                                                               |
| `appearance.window_button_position`        | string | `left`         | Which end of the title bar the window controls sit on Values: `right`, `left`. `--window-button-position` sets it for one run.                                                                                                                                                                    |
| `appearance.window_button_style`           | string | `dots`         | Window controls as a filled pill or as macOS traffic lights Values: `pill`, `dots`. `--window-button-style` sets it for one run.                                                                                                                                                                  |
| `appearance.window_button_zoom`            | bool   | `true`         | Carry the third title bar control on a tiled pane, where it toggles the zoom                                                                                                                                                                                                                      |
| `appearance.window_chrome_background`      | string | empty          | Background under pane borders and title bars, the lines between shared-border panes and the capture marquee: off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background                                                                            |
| `appearance.window_title_align`            | string | `auto`         | Where a pane's title sits on its row. auto is the end away from the window buttons on the top row, and the middle on the bottom row. left, center and right are that place in the room the buttons leave Values: `auto`, `left`, `center`, `right`.                                               |
| `appearance.window_title_format`           | string | empty          | Title template accepting {title}, {index} and {cwd}                                                                                                                                                                                                                                               |
| `appearance.window_title_position`         | string | `top`          | Edge of the pane the title is drawn on Values: `bottom`, `top`, `hidden`. `--window-title-position` sets it for one run.                                                                                                                                                                          |
| `appearance.window_title_style`            | string | `pill`         | Shape of a pane's title: pill is the name on a fill in the border's colour, with rounded caps; tab is the fill with no caps; plain is the name in the border's colour, with no fill Values: `pill`, `tab`, `plain`.                                                                               |
| `appearance.word_characters`               | string | `@-./_~?&=%+#` | Punctuation that counts as part of a word for double-click selection                                                                                                                                                                                                                              |
| `appearance.workspace_transition`          | string | empty          | Old name of motion.workspace Deprecated: folded into motion.workspace on load; set motion.workspace                                                                                                                                                                                               |
| `appearance.workspace_transition_ms`       | int    | empty          | Old name of motion.workspace\_ms Range: 0 to 1000. Deprecated: folded into motion.workspace\_ms on load; set motion.workspace\_ms                                                                                                                                                                 |
| `appearance.wrap_lists`                    | bool   | `true`         | Up on a list's first row goes to its last, and down on the last goes to the first                                                                                                                                                                                                                 |
| `appearance.zen_mode`                      | string | `disabled`     | When window borders are hidden: never, always, or while the mouse is idle Values: `disabled`, `always`, `mouse`.                                                                                                                                                                                  |
| `appearance.zen_reveal_ms`                 | int    | `2000`         | Milliseconds the pointer sits still before zen mode (mouse) hides the borders again Range: 200 to 30000.                                                                                                                                                                                          |
| `appearance.zoom_animation`                | bool   | empty          | Old name of motion.zoom Deprecated: folded into motion.zoom on load; set motion.zoom                                                                                                                                                                                                              |
| `appearance.zoom_borderless`               | bool   | `false`        | Show a zoomed pane on the whole pane region with no border or title bar. Zoom size and zoom max width do not apply.                                                                                                                                                                               |
| `appearance.zoom_follows_focus`            | bool   | `true`         | Hand the zoom to the pane the focus lands on, so moving focus while zoomed shows the pane you moved to                                                                                                                                                                                            |
| `appearance.zoom_max_width`                | int    | `0`            | Width in cells of a zoomed pane. 0 fills the screen. `--zoom-max-width` sets it for one run.                                                                                                                                                                                                      |
| `appearance.zoom_size`                     | int    | `95`           | How much of the screen a zoomed pane takes, as a percent. Below 100 the layout around it stays visible at the edges. Range: 50 to 100.                                                                                                                                                            |
| `shell.integration`                        | string | `auto`         | Turn on prompt marks in the bash and zsh shells that new panes start. Your files do not change. off starts each shell as it is Values: `auto`, `off`.                                                                                                                                             |
| `shell.login`                              | bool   | `false`        | Start the shell of each new pane as a login shell, so it reads .zprofile, .bash\_profile or .profile, as a terminal on macOS does                                                                                                                                                                 |

## dock

| Option                                 | Type   | Default   | Description                                                                                                                                                |
| -------------------------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance.clock_format`              | string | `15:04`   | Go time layout the clock is drawn with, e.g. 15:04 or Mon 3:04PM                                                                                           |
| `appearance.dock_background`           | string | empty     | Background under the dock: off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background                       |
| `appearance.dock_compact`              | bool   | `false`   | Draw the dock as one row with no rule. The panes get one more row                                                                                          |
| `appearance.dock_mode_icon_terminal`   | string | `default` | Icon in the mode pill in terminal mode. An empty value shows no icon. default uses the icon of the glyph set                                               |
| `appearance.dock_mode_icon_tiling`     | string | `default` | Icon in the mode pill while tiling is on. An empty value shows no icon. default uses the icon of the glyph set                                             |
| `appearance.dock_mode_icon_window`     | string | `default` | Icon in the mode pill in window mode. An empty value shows no icon. default uses the icon of the glyph set                                                 |
| `appearance.dock_mode_pill`            | string | `tiling`  | What the mode pill shows while tiling is on: tiling shows the tiling icon, input shows the terminal or window icon Values: `tiling`, `input`.              |
| `appearance.dock_mode_split_letter`    | bool   | `true`    | Show V or H after the tiling icon in the mode pill. The letter is the direction of the next split                                                          |
| `appearance.dock_pill_caps`            | bool   | `true`    | Draw rounded caps on every dock pill: the mode chip, the workspace tabs and the minimized windows. Off draws flat pills                                    |
| `appearance.dock_prefix_indicator`     | string | `pill`    | Where the dock shows an armed leader key: pill colours the mode pill, badge draws a separate badge Values: `pill`, `badge`.                                |
| `appearance.dock_workspace_label_max`  | int    | `12`      | Cells a workspace pill's label may span before the pill cuts it (0 draws the whole name and scrolls the strip instead) Range: 0 to 200.                    |
| `appearance.dock_workspace_tab_format` | string | empty     | Workspace tab template accepting {index}, {name}, {icon} and {zoom} (empty: {name}). With {index} in it, an unnamed workspace shows only its number        |
| `appearance.dock_workspace_tabs`       | bool   | `true`    | Show the clickable workspace strip in the dock                                                                                                             |
| `appearance.dock_workspace_tooltip`    | bool   | `true`    | Show the workspace name on hover when the pill cuts the name or does not show it                                                                           |
| `appearance.dockbar_position`          | string | `top`     | Edge the dock sits on, or hidden Values: `bottom`, `top`, `hidden`. `--dockbar-position` sets it for one run.                                              |
| `appearance.hide_clock`                | bool   | `false`   | Hide the clock overlay `--hide-clock` sets it for one run. Deprecated: superseded by appearance.show\_clock, which says the same thing the right way round |
| `appearance.show_clock`                | bool   | `false`   | Show the clock overlay `--show-clock` sets it for one run.                                                                                                 |
| `appearance.show_cpu`                  | bool   | `false`   | Show the CPU graph in the dock `--show-cpu` sets it for one run.                                                                                           |
| `appearance.show_ram`                  | bool   | `false`   | Show RAM usage in the dock `--show-ram` sets it for one run.                                                                                               |
| `dock.clock.format`                    | string | empty     | Go time layout the clock renders in (empty means 15:04); a layout without seconds refreshes once a minute                                                  |
| `dock.meter_interval_ms`               | int    | `2000`    | Milliseconds between measurements of the dock's CPU and RAM readouts Range: 500 to 60000.                                                                  |

## sidebar

| Option                                      | Type   | Default                                    | Description                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance.git_dirty`                      | bool   | `true`                                     | Count staged, changed and untracked paths in the rail's git section. The only part of it that costs a walk of the working tree.                                                                                                                                              |
| `appearance.sidebar.agent_rest_fold`        | string | `1h`                                       | How long an agent row rests (idle, unknown, or done and seen) before the rail folds it into one line: a duration such as 1h, or off                                                                                                                                          |
| `appearance.sidebar.background`             | string | empty                                      | Background under the rail: off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background                                                                                                                                         |
| `appearance.sidebar.cursor_background`      | string | empty                                      | Background of the row under the cursor while the rail has the keyboard: a colour (#rrggbb, 0-255, a slot name or a role name); empty keeps the theme's                                                                                                                       |
| `appearance.sidebar.density`                | string | `normal`                                   | Space between the rail's sections: normal, or roomy for a blank row in front of each section after the first Values: `normal`, `roomy`.                                                                                                                                      |
| `appearance.sidebar.editor`                 | string | empty                                      | The terminal editor that opens a text file. If this is empty, tuios uses $EDITOR, then $VISUAL, then vi.                                                                                                                                                                     |
| `appearance.sidebar.enabled`                | bool   | `true`                                     | Show the session rail                                                                                                                                                                                                                                                        |
| `appearance.sidebar.file_actions`           | bool   | `true`                                     | Let the files section create, rename, delete, copy and paste                                                                                                                                                                                                                 |
| `appearance.sidebar.file_delete`            | string | `trash`                                    | Where a delete sends the file: the trash, or nowhere Values: `trash`, `permanent`.                                                                                                                                                                                           |
| `appearance.sidebar.file_drag`              | bool   | `true`                                     | Drag a row of the files section into a pane to paste its path                                                                                                                                                                                                                |
| `appearance.sidebar.file_icon_colors`       | bool   | `true`                                     | Draw each file icon in its file type's own colour                                                                                                                                                                                                                            |
| `appearance.sidebar.file_icons`             | bool   | `true`                                     | Draw a nerd font icon per file type in the files section                                                                                                                                                                                                                     |
| `appearance.sidebar.files_style`            | string | `list`                                     | How the files section draws: list shows one folder at a time, tree opens folders in place under one root Values: `list`, `tree`.                                                                                                                                             |
| `appearance.sidebar.folder_click`           | string | `navigate`                                 | What a click on a folder row does Values: `navigate`, `cd`, `both`.                                                                                                                                                                                                          |
| `appearance.sidebar.git_refresh_ms`         | int    | `2000`                                     | Milliseconds between the git section's looks at a directory it is showing. git runs only when the commits have moved. Raise it for a very large repository. Range: 500 to 60000.                                                                                             |
| `appearance.sidebar.group_main`             | bool   | `false`                                    | Give each repository a row of its own, with the main checkout under it. When off, the main checkout's row is the repository's row                                                                                                                                            |
| `appearance.sidebar.header_case`            | string | `lowercase`                                | How the rail's section headers read: lowercase keeps the quiet furniture look, uppercase draws them as headings Values: `lowercase`, `uppercase`.                                                                                                                            |
| `appearance.sidebar.header_style`           | string | `auto`                                     | How a rail section header is drawn: auto, plain, rule, pill, or icon with the section's icon Values: `auto`, `plain`, `rule`, `pill`, `icon`.                                                                                                                                |
| `appearance.sidebar.marquee`                | bool   | `true`                                     | Scroll a hovered row's overflowing title                                                                                                                                                                                                                                     |
| `appearance.sidebar.marquee_pause_ms`       | int    | `900`                                      | Milliseconds a hovered row holds still before its overflowing title starts to move. 0 starts at once Range: 0 to 10000.                                                                                                                                                      |
| `appearance.sidebar.marquee_step_ms`        | int    | `220`                                      | Milliseconds each one-cell step of the rail's marquee is held. Larger is slower. Range: 20 to 2000.                                                                                                                                                                          |
| `appearance.sidebar.peek`                   | bool   | `true`                                     | Show a session's panes in the terminals section while the pointer or the rail cursor is on its row                                                                                                                                                                           |
| `appearance.sidebar.per_session`            | bool   | `false`                                    | Each session keeps its own shown or hidden rail. Off, showing or hiding the rail applies to every session                                                                                                                                                                    |
| `appearance.sidebar.position`               | string | `right`                                    | Edge the rail sits on, or hidden Values: `left`, `right`, `hidden`.                                                                                                                                                                                                          |
| `appearance.sidebar.row_style`              | string | `bar`                                      | How the rail marks the row you are on: bar in the gutter, marker glyph, underline, or pill Values: `bar`, `marker`, `underline`, `pill`.                                                                                                                                     |
| `appearance.sidebar.sections`               | string | `sessions:25,terminals,files:25,agents:34` | Section names in the order the rail stacks them, each with an optional percent share. A name left out is a section the rail does not draw, and "spacer" is an empty block you may repeat. The files control at the foot of the rail adds files to this list or takes it out. |
| `appearance.sidebar.show_agents`            | bool   | `true`                                     | Show the agents section at the rail's bottom Deprecated: folded into appearance.sidebar.sections on load; leave agents out of the layout                                                                                                                                     |
| `appearance.sidebar.show_counts`            | bool   | `true`                                     | Show the window count on each session row                                                                                                                                                                                                                                    |
| `appearance.sidebar.show_glyphs`            | bool   | `true`                                     | Show the agent-state glyph on each row                                                                                                                                                                                                                                       |
| `appearance.sidebar.show_numbers`           | bool   | `false`                                    | Show the switch number ahead of each session name                                                                                                                                                                                                                            |
| `appearance.sidebar.show_windows`           | bool   | `true`                                     | Show the terminals section Deprecated: folded into appearance.sidebar.sections on load; leave terminals out of the layout                                                                                                                                                    |
| `appearance.sidebar.subagent_collapse`      | string | `off`                                      | A heading line over each agent's subagents that opens and shuts their rows: off, or on and expanded or collapsed at the start Values: `off`, `expanded`, `collapsed`.                                                                                                        |
| `appearance.sidebar.subagent_fields`        | string | `mark,name,time,note`                      | What each subagent row shows, a comma list of mark, name, type, time and note. type is the agent type, such as Explore. note is the second line                                                                                                                              |
| `appearance.sidebar.subagent_hide_finished` | string | `off`                                      | How long a finished subagent's row stays after it ends: a duration such as 30s, or off to keep it until the daemon drops it                                                                                                                                                  |
| `appearance.sidebar.subagent_max_rows`      | int    | `0`                                        | The most lines one agent's subagents take, the +N more line included. 0 is no limit. Range: 0 to 16.                                                                                                                                                                         |
| `appearance.sidebar.subagent_rows`          | string | `rows`                                     | How an agent row shows its subagents: a row for each under it, the rows on tree lines, or the count alone Values: `rows`, `tree`, `count`.                                                                                                                                   |
| `appearance.sidebar.tooltips`               | bool   | `true`                                     | Label the collapsed strip on hover                                                                                                                                                                                                                                           |
| `appearance.sidebar.width`                  | int    | `24`                                       | Preferred rail width in columns on a wide screen                                                                                                                                                                                                                             |
| `appearance.sidebar.workspaces`             | string | empty                                      | Workspace chip band the rail used to draw Deprecated: no longer used: panes name their own workspace, and switching lives on the dock and alt+1..9                                                                                                                           |

## scrollbar

| Option                       | Type   | Default | Description                                                                                |
| ---------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------ |
| `appearance.scrollbar.style` | string | `track` | Hairline thumb over the content column, or a full-height track Values: `thin`, `track`.    |
| `appearance.scrollbar.thumb` | string | empty   | One-cell glyph for the thumb. Empty uses the style's own.                                  |
| `appearance.scrollbar.tint`  | string | `quiet` | Bar colour: quiet, border, muted, or a colour (#rrggbb, 0-255, a slot name or a role name) |
| `appearance.scrollbar.track` | string | empty   | One-cell glyph for the track, or none. Empty uses the style's own.                         |

## selection

| Option                              | Type   | Default    | Description                                                                                                                                                  |
| ----------------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appearance.selection.bg`           | string | `#45475A`  | Background behind selected text                                                                                                                              |
| `appearance.selection.bold`         | bool   | `false`    | Draw selected text bold as well as tinted                                                                                                                    |
| `appearance.selection.copy_command` | string | empty      | A command that gets each copy mode yank on stdin. Its output goes to the clipboard. If this is empty, tuios copies the selection as it is.                   |
| `appearance.selection.copy_entry`   | string | `cursor`   | Where copy mode puts its cursor: on the terminal cursor or in the center Values: `cursor`, `center`.                                                         |
| `appearance.selection.cursor_bg`    | string | `#39C5CF`  | Background of the copy mode cursor block                                                                                                                     |
| `appearance.selection.cursor_fg`    | string | `#08222B`  | Text colour under the copy mode cursor. Empty keeps it.                                                                                                      |
| `appearance.selection.fg`           | string | empty      | Selected text colour. Empty keeps the colour it already has.                                                                                                 |
| `appearance.selection.flash`        | bool   | `true`     | Sweep a band of light over text that was just copied. Set motion to none to turn it off.                                                                     |
| `appearance.selection.flash_color`  | string | empty      | The light the copy sweep is made of                                                                                                                          |
| `appearance.selection.flash_ms`     | int    | `420`      | Milliseconds one copy sweep takes Range: 80 to 3000.                                                                                                         |
| `appearance.selection.flash_style`  | string | `diagonal` | The shape the copy sweep takes Values: `diagonal`, `diagonal-reverse`, `horizontal`, `vertical`.                                                             |
| `appearance.selection.match_bg`     | string | `#E5A93D`  | Background behind the match the cursor is on                                                                                                                 |
| `appearance.selection.match_fg`     | string | `#1C1B19`  | Text colour of the match the cursor is on. Empty keeps it.                                                                                                   |
| `appearance.selection.multi_format` | string | `plain`    | The format multi copy mode yanks in: plain, markdown or json Values: `plain`, `markdown`, `json`.                                                            |
| `appearance.selection.osc52_write`  | string | `focused`  | What happens when a program in a pane sets the clipboard: off, ask, focused (the focused pane only, others ask) or on Values: `off`, `ask`, `focused`, `on`. |
| `appearance.selection.search_bg`    | string | `#8A6D2F`  | Background behind every search match                                                                                                                         |
| `appearance.selection.search_fg`    | string | `#F5E7C8`  | Text colour of a search match. Empty keeps the colour it has.                                                                                                |
| `paste_buffers.limit`               | int    | `20`       | How many yanks to keep to paste again. When it is full, the oldest goes. 0 keeps none. Range: 0 to 1000.                                                     |
| `paste_buffers.max_kb`              | int    | `16384`    | Most KiB all paste buffers hold together, at most 262144 (256 MiB). When it is full, the oldest go. 0 uses 16384. Range: 0 to 262144.                        |

## daemon

| Option                                  | Type   | Default  | Description                                                                                                                                                                                           |
| --------------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daemon.agent_autodetect`               | bool   | `true`   | Detect a pane's foreground agent CLI and set its state glyph The `TUIOS_AGENT_AUTODETECT` environment variable sets it too, and wins over the file.                                                   |
| `daemon.agent_detect_seconds`           | int    | `2`      | Seconds between checks. 0 uses 2. A negative number turns checks off. The `TUIOS_AGENT_DETECT_SECONDS` environment variable sets it too, and wins over the file.                                      |
| `daemon.agent_stall_seconds`            | int    | `30`     | Seconds of silence after which a working agent shows as unknown. 0 uses 30. A negative number turns it off. The `TUIOS_AGENT_STALL_SECONDS` environment variable sets it too, and wins over the file. |
| `daemon.cleanup_seconds`                | int    | `30`     | Seconds between releases of the memory that pane output leaves behind. 0 uses 30. The `TUIOS_CLEANUP_SECONDS` environment variable sets it too, and wins over the file.                               |
| `daemon.client_follows_upgrade`         | bool   | `true`   | After a live upgrade of the daemon to a newer build, a client on this machine runs the new build too, on the same terminal and session.                                                               |
| `daemon.dispatch_ready_seconds`         | int    | `0`      | Seconds a dispatched task waits for its agent to be ready, at most 600. 0 uses the start-agent wait. The `TUIOS_DISPATCH_READY_SECONDS` environment variable sets it too, and wins over the file.     |
| `daemon.exec_timeout_seconds`           | int    | `30`     | Seconds a command run with tuios exec may take when the caller names no timeout. 0 uses 30 Range: 0 to 3600.                                                                                          |
| `daemon.host_call_timeout_seconds`      | int    | `8`      | Seconds one listing over a live link may take before the link is dialed again. 0 uses 8 Range: 0 to 120.                                                                                              |
| `daemon.host_heartbeat_seconds`         | int    | `15`     | Seconds a link to another machine may carry nothing before the daemon pings it. 0 uses 15 Range: 0 to 300.                                                                                            |
| `daemon.host_heartbeat_timeout_seconds` | int    | `5`      | Seconds one ping to another machine waits for its reply. Two misses end the link. 0 uses 5 Range: 0 to 60.                                                                                            |
| `daemon.keep_awake`                     | string | `off`    | Keep the machine from sleeping: while an agent works on this machine, while the daemon runs, or never. The display can still lock. Values: `off`, `agents`, `on`.                                     |
| `daemon.log_level`                      | string | `off`    | How much the daemon logs Values: `off`, `errors`, `basic`, `messages`, `verbose`, `trace`.                                                                                                            |
| `daemon.persist_scrollback`             | bool   | `true`   | Save each pane's history and show it again after a daemon restart. A change applies when the daemon next starts.                                                                                      |
| `daemon.persist_scrollback_kb`          | int    | `0`      | Most KiB one pane's saved history takes on disk. 0 uses 2048. A change applies when the daemon next starts. Range: 0 to 1048576.                                                                      |
| `daemon.persist_scrollback_lines`       | int    | `0`      | Most history lines one pane saves. 0 uses 1000. A change applies when the daemon next starts. Range: 0 to 1000000.                                                                                    |
| `daemon.pr_poll_seconds`                | int    | `60`     | Seconds between checks of the pull requests the sidebar shows. 0 uses 60. The `TUIOS_PR_POLL_SECONDS` environment variable sets it too, and wins over the file.                                       |
| `daemon.reconnect_seconds`              | int    | `15`     | Seconds a client waits for a restarted daemon before it gives up. 0 uses 15 Range: 0 to 300.                                                                                                          |
| `daemon.resume_agents`                  | string | `ask`    | After a daemon restart, ask to resume each pane's agent conversation, resume it, or do neither Values: `ask`, `auto`, `off`.                                                                          |
| `daemon.save_seconds`                   | int    | `30`     | Most seconds a session whose panes printed waits to be saved, which keeps each pane's folder current for a restore Range: 10 to 600.                                                                  |
| `daemon.subagent_fade_seconds`          | int    | `60`     | Seconds a finished subagent stays in the list. A failed one stays five times as long. 0 uses 60. The `TUIOS_SUBAGENT_FADE_SECONDS` environment variable sets it too, and wins over the file.          |
| `daemon.transfer_keep_seconds`          | int    | `1800`   | Seconds a finished file transfer stays in the list. 0 uses 1800. The `TUIOS_TRANSFER_KEEP_SECONDS` environment variable sets it too, and wins over the file.                                          |
| `daemon.window_size`                    | string | `latest` | The size of a session with more than one client: the client that last had input, the smallest client, or the largest client Values: `smallest`, `largest`, `latest`.                                  |

## debug

| Option                  | Type | Default | Description                                                                             |
| ----------------------- | ---- | ------- | --------------------------------------------------------------------------------------- |
| `debug.show_key_count`  | int  | `5`     | How many recent keypresses the showkeys overlay keeps, for a screencast Range: 1 to 20. |
| `debug.show_key_events` | bool | `false` | Show the on-screen keycast of recent keypresses                                         |

## files

| Option                      | Type | Default | Description                                                                                                                                          |
| --------------------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `files.drop_keep_hours`     | int  | `24`    | Hours a file dropped into a pane of another machine stays in that machine's drop folder. 0 uses 24 Range: 0 to 8760.                                 |
| `files.drop_keep_mb`        | int  | `256`   | Most MiB the drop folder holds. A drop that does not fit is refused. 0 uses 256 Range: 0 to 65536.                                                   |
| `files.open_copy_ask_mb`    | int  | `200`   | Above this size in MiB, o on a file of another machine shows the size and asks again before it copies the file here. 0 uses 200 Range: 0 to 1048576. |
| `files.open_copy_keep_days` | int  | `7`     | Days a copy of a far file stays when nobody opens it again. 0 uses 7, and -1 keeps every copy Range: -1 to 3650.                                     |
| `files.open_copy_max_mb`    | int  | `4096`  | Above this size in MiB, o on a file of another machine does not copy it here. 0 uses 4096 Range: 0 to 1048576.                                       |

## hints

| Option            | Type   | Default     | Description                                                                      |
| ----------------- | ------ | ----------- | -------------------------------------------------------------------------------- |
| `hints.all_panes` | bool   | `false`     | The hints key labels every pane on the workspace, not only the focused pane      |
| `hints.alphabet`  | string | `asdfghjkl` | Letters the hint labels are made of, easiest first                               |
| `hints.builtins`  | string | `all`       | Built-in patterns hints mode looks for: all, none, or names such as url,path,sha |
| `hints.dim`       | int    | `60`        | Percent of its light the text around the hints loses Range: 10 to 90.            |
| `hints.open`      | bool   | `true`      | Ctrl and a label opens the URL or path. It does not open on a remote client      |

## launcher

| Option                 | Type   | Default | Description                                                                                                                                                                                                                                                                                                           |
| ---------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `launcher.gui_command` | string | empty   | Command that starts a graphical desktop entry instead of a pane. The entry's argv is added to it. Use a command that takes an argv, such as "tuios-wayland launch --" or "niri msg action spawn --". Do not use one that joins its arguments into a shell line, such as "swaymsg exec --" or "hyprctl dispatch exec". |
| `launcher.keep_open`   | bool   | `false` | Keep the pane of a program the launcher started after the program exits. A line under the output shows the exit status. Needs a daemon session.                                                                                                                                                                       |

## mermaid

| Option               | Type   | Default | Description                                                                                                                             |
| -------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `mermaid.background` | string | `theme` | Background of a tuios mermaid picture: theme for the theme's colour, or none for the terminal's own background Values: `theme`, `none`. |
| `mermaid.theme`      | string | `tuios` | Colours of tuios mermaid: tuios for the colours of your theme, or a named theme such as flexoki, nord or rose-pine                      |

## motion

| Option                | Type   | Default | Description                                                                                                                 |
| --------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `motion.confetti`     | string | `on`    | The confetti burst: on or off. It needs appearance.motion = "full" Values: `on`, `off`.                                     |
| `motion.copy`         | string | `on`    | A sweep crosses the cells a copy took: on or off Values: `on`, `off`.                                                       |
| `motion.layout`       | string | `on`    | Panes slide when they open, close, split, swap, snap, minimize or restore: on or off Values: `on`, `off`.                   |
| `motion.layout_ms`    | int    | `300`   | Milliseconds the layout motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.                                  |
| `motion.overlays`     | string | `on`    | A palette or dialog fades in as it opens: on or off. It needs appearance.motion = "full" and truecolor Values: `on`, `off`. |
| `motion.overlays_ms`  | int    | `120`   | Milliseconds the overlays motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.                                |
| `motion.scroll`       | string | `on`    | The scrolling layout slides when the view moves: on or off Values: `on`, `off`.                                             |
| `motion.scroll_ms`    | int    | `300`   | Milliseconds the scroll motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.                                  |
| `motion.sidebar`      | string | `on`    | The shimmer on a working agent row of the sidebar: on or off. It needs appearance.motion = "full" Values: `on`, `off`.      |
| `motion.workspace`    | string | `slide` | How tuios shows a workspace switch: slide, fade or none. With 16 colours, fade is a cut Values: `slide`, `fade`, `none`.    |
| `motion.workspace_ms` | int    | `200`   | Milliseconds the workspace motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.                               |
| `motion.zoom`         | string | `on`    | A pane slides between its tile and the zoom box: on or off Values: `on`, `off`.                                             |
| `motion.zoom_ms`      | int    | `200`   | Milliseconds the zoom motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.                                    |

## mouse

| Option                  | Type | Default | Description                                                                                                                                                               |
| ----------------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mouse.double_click_ms` | int  | `300`   | Milliseconds after a click in which a second one counts as a double click: in a pane, on the rail divider, in the Agents list and in the draft editor Range: 100 to 1000. |
| `mouse.drag_threshold`  | int  | `5`     | Cells the pointer moves before a press is a drag and not a click. It applies to the right button, to click-to-type and to Ctrl drag Range: 1 to 50.                       |

## notifications

| Option                                       | Type   | Default                               | Description                                                                                                                                                                                                   |
| -------------------------------------------- | ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notifications.agent.command`                | string | empty                                 | Shell command to run on an alert. Empty runs nothing.                                                                                                                                                         |
| `notifications.agent.dock`                   | bool   | `true`                                | Show the alert in the dock. Click it to go to the pane.                                                                                                                                                       |
| `notifications.agent.enabled`                | bool   | `true`                                | Turn every agent alert on or off                                                                                                                                                                              |
| `notifications.agent.notify`                 | bool   | `true`                                | Send a desktop notification to the attached terminal                                                                                                                                                          |
| `notifications.agent.quiet_hours`            | string | empty                                 | Hours when nothing alerts. Write it as HH:MM-HH:MM.                                                                                                                                                           |
| `notifications.agent.settle_seconds`         | int    | `2`                                   | Seconds to wait. tuios drops the alert if the pane changes state. Range: 0 to 3600.                                                                                                                           |
| `notifications.agent.sound`                  | bool   | `false`                               | Make an alert audible                                                                                                                                                                                         |
| `notifications.agent.sound_cooldown_seconds` | int    | `3`                                   | Shortest gap between two sounds, in seconds. 0 uses 3. Range: 0 to 3600.                                                                                                                                      |
| `notifications.agent.sound_mode`             | string | empty                                 | How an alert sounds: a cue, a BEL, or both Values: `audio`, `bell`, `both`.                                                                                                                                   |
| `notifications.agent.states.done`            | bool   | `true`                                | Alert when an agent reports it finished                                                                                                                                                                       |
| `notifications.agent.states.errored`         | bool   | `true`                                | Alert when an agent stops on an error                                                                                                                                                                         |
| `notifications.agent.states.idle`            | bool   | `false`                               | Alert when an agent goes quiet                                                                                                                                                                                |
| `notifications.agent.states.needs_input`     | bool   | `true`                                | Alert when an agent waits for you                                                                                                                                                                             |
| `notifications.agent.states.working`         | bool   | `false`                               | Alert when an agent starts work                                                                                                                                                                               |
| `notifications.agent.suppress_focused`       | bool   | `true`                                | No alert for the focused pane while the terminal has focus                                                                                                                                                    |
| `notifications.bell`                         | string | `toast`                               | What a pane's bell does: a dock message, a bell in your terminal, both, or nothing Values: `toast`, `forward`, `both`, `off`.                                                                                 |
| `notifications.bell_rate_limit_ms`           | int    | `200`                                 | Milliseconds in which a second bell from a pane is dropped. 0 keeps every one. Range: 0 to 10000.                                                                                                             |
| `notifications.duration`                     | int    | `0`                                   | Seconds an info message stays up. 0 uses the default, 2. Range: 0 to 3600.                                                                                                                                    |
| `notifications.error_duration`               | int    | `0`                                   | Seconds an error stays up when error\_sticky is false. 0 uses the default, 15. Range: 0 to 3600.                                                                                                              |
| `notifications.error_sticky`                 | bool   | `true`                                | Make errors wait for esc instead of expiring                                                                                                                                                                  |
| `notifications.level`                        | string | `info`                                | The least severe tuios message the dock shows: info shows every message, warning only warnings and errors, error only errors. Agent and pane alerts do not use this level Values: `info`, `warning`, `error`. |
| `notifications.log_hidden`                   | bool   | `true`                                | Put messages below notifications.level in the log viewer. When off, they go nowhere. Warnings and errors always go to the log                                                                                 |
| `notifications.machine_offer`                | bool   | `true`                                | Offer to add a machine when a pane logs in to it with ssh or mosh and no \[hosts] entry reaches it                                                                                                            |
| `notifications.mail.between_agents`          | bool   | `false`                               | Alert on a message from one agent to another agent too.                                                                                                                                                       |
| `notifications.mail.dock`                    | bool   | follows `notifications.agent.dock`    | Show a mail alert in the dock. Unset follows notifications.agent.dock.                                                                                                                                        |
| `notifications.mail.enabled`                 | bool   | follows `notifications.agent.enabled` | Turn mail alerts on or off. Unset follows notifications.agent.enabled.                                                                                                                                        |
| `notifications.mail.notify`                  | bool   | follows `notifications.agent.notify`  | Send a desktop notification for mail. Unset follows notifications.agent.notify.                                                                                                                               |
| `notifications.mail.sound`                   | bool   | follows `notifications.agent.sound`   | Make a mail alert audible. Unset follows notifications.agent.sound.                                                                                                                                           |
| `notifications.rate_limit_ms`                | int    | `500`                                 | Milliseconds in which a second desktop notification from a pane is dropped. 0 keeps every one. Range: 0 to 10000.                                                                                             |
| `notifications.style`                        | string | `full`                                | How a dock message looks: full shows a side bar and a countdown line, plain shows the icon and the text only Values: `full`, `plain`.                                                                         |
| `notifications.warning_duration`             | int    | `0`                                   | Seconds a warning stays up. 0 uses the default, 8. Range: 0 to 3600.                                                                                                                                          |

## panes

| Option                        | Type   | Default      | Description                                                                              |
| ----------------------------- | ------ | ------------ | ---------------------------------------------------------------------------------------- |
| `panes.drag_and_drop`         | bool   | `false`      | Drag and drop between panes over the kitty drag and drop protocol (OSC 72)               |
| `panes.drag_and_drop_desktop` | bool   | `false`      | Bridge drags to and from the desktop through a terminal that speaks the protocol (kitty) |
| `panes.label_keys`            | string | `1234567890` | Keys the pane labels are made of, first pane first. Letters a to z and digits            |
| `panes.navigator_layout`      | string | `tree`       | How the pane navigator lists the panes when it opens Values: `tree`, `flat`, `cards`.    |
| `panes.navigator_search`      | bool   | `false`      | Open the pane navigator ready to type a search                                           |
| `path_picker.show_hidden`     | bool   | `false`      | The path picker lists hidden files. Alt+h in the picker shows or hides them              |

## pip

| Option       | Type   | Default        | Description                                                                                                                                                            |
| ------------ | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pip.corner` | string | `bottom-right` | Corner the picture-in-picture view goes to first. It moves to another corner when the cursor enters it Values: `bottom-right`, `bottom-left`, `top-right`, `top-left`. |
| `pip.height` | int    | `12`           | Height of the picture-in-picture view, border included, in cells Range: 3 to 100.                                                                                      |
| `pip.width`  | int    | `40`           | Width of the picture-in-picture view, border included, in cells Range: 12 to 200.                                                                                      |

## review

| Option         | Type   | Default | Description                                                                                                                                            |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `review.focus` | string | `diff`  | Which side of the review overlay has the keys when a review opens: the diff or the file list Values: `diff`, `files`.                                  |
| `review.scope` | string | `base`  | What a review shows when it opens: the changes since the base, or only the uncommitted changes. u switches between them Values: `base`, `uncommitted`. |

## scratch

| Option           | Type   | Default | Description                                                    |
| ---------------- | ------ | ------- | -------------------------------------------------------------- |
| `scratch.height` | string | `80%`   | Height of the scratch terminal, in cells (20) or percent (80%) |
| `scratch.width`  | string | `80%`   | Width of the scratch terminal, in cells (60) or percent (80%)  |

## screensaver

| Option                     | Type   | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `screensaver.effect`       | string | `random` | Which effect runs, or random for a different one each time Values: `random`, `binarypath`, `blackhole`, `bouncyballs`, `bubbles`, `burn`, `crumble`, `decrypt`, `errorcorrect`, `expand`, `fireworks`, `highlight`, `laseretch`, `matrix`, `middleout`, `orbittingvolley`, `overflow`, `pour`, `print`, `rain`, `randomsequence`, `rings`, `scattered`, `slice`, `slide`, `smoke`, `spotlights`, `spray`, `swarm`, `sweep`, `synthgrid`, `thunderstorm`, `tuffbaby`, `unstable`, `vhstape`, `waves`, `wipe`. |
| `screensaver.enabled`      | bool   | `false`  | Animate the screen after a spell with no input                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `screensaver.idle_minutes` | int    | `10`     | Minutes of quiet before the screen saver starts Range: 1 to 240.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `screensaver.while_busy`   | bool   | `false`  | Start even when a pane is running a command or an agent                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## screenshot

| Option                    | Type   | Default                     | Description                                                                                                |
| ------------------------- | ------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `screenshot.background`   | string | `auto`                      | Wash behind the card: auto derives it from the theme; none, a hex color, or hex..hex work too              |
| `screenshot.controls`     | string | `auto`                      | Window control marks: the macOS lights, your glyph set, or none Values: `auto`, `macos`, `glyphs`, `none`. |
| `screenshot.copy`         | bool   | `true`                      | Try to copy the capture to the clipboard                                                                   |
| `screenshot.cursor`       | bool   | `false`                     | Draw the cursor cell in the capture                                                                        |
| `screenshot.directory`    | string | `~/Pictures/tuios`          | Folder where capture files are saved                                                                       |
| `screenshot.font_family`  | string | `JetBrains Mono, monospace` | Font to draw the capture in when your terminal does not say which it uses                                  |
| `screenshot.font_file`    | string | empty                       | Font file to draw PNG with, also embedded in SVG and HTML. It wins over every other font choice.           |
| `screenshot.format`       | string | `png`                       | Default output format for captures Values: `png`, `svg`, `ansi`, `html`, `txt`.                            |
| `screenshot.frame`        | string | `window`                    | Dressing around the capture: a window card, a plain card, or nothing Values: `window`, `plain`, `none`.    |
| `screenshot.padding`      | int    | `48`                        | Space around the card in pixels Range: 0 to 128.                                                           |
| `screenshot.preview`      | bool   | `true`                      | Open the preview panel after a capture                                                                     |
| `screenshot.radius`       | int    | `10`                        | Card corner radius in pixels Range: 0 to 32.                                                               |
| `screenshot.scale`        | int    | `2`                         | PNG size multiplier Range: 1 to 4.                                                                         |
| `screenshot.shadow`       | bool   | `true`                      | Draw a soft shadow under the card                                                                          |
| `screenshot.title_format` | string | `{title}`                   | Title bar text of a screenshot: {title} (the window title as its title bar shows it), {index} and {cwd}    |

## spotlight

| Option              | Type   | Default | Description                                                                                                                                |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `spotlight.dim`     | int    | `75`    | Percent of its light an unlit cell loses Range: 10 to 95.                                                                                  |
| `spotlight.edge`    | string | `hard`  | Cut the beam at its edge, or fade it out. A fade sends about three times the bytes each time the beam moves Values: `hard`, `soft`.        |
| `spotlight.enabled` | bool   | `false` | Light one part of the screen and dim the rest                                                                                              |
| `spotlight.follow`  | string | `mouse` | What the beam follows: the mouse, or the focused pane's cursor. The cursor sends fewer bytes to a remote client Values: `cursor`, `mouse`. |
| `spotlight.radius`  | int    | `10`    | Half the beam's height, in rows Range: 2 to 200.                                                                                           |
| `spotlight.shake`   | bool   | `false` | Move the mouse left and right fast to turn the beam on and off. A shake does not move the beam. The follow setting decides where it goes   |

## startup

| Option                           | Type   | Default | Description                                                                                                                                                                                |
| -------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `startup.daemon`                 | bool   | `true`  | Make a bare "tuios" attach to a daemon-backed session instead of running standalone. TUIOS\_NO\_DAEMON=1 or --standalone overrides it. False when the config file has no \[startup] table. |
| `startup.layout`                 | string | `bsp`   | Tiling scheme a new session starts in. An existing session keeps its own. Values: `bsp`, `master-stack`, `scrolling`.                                                                      |
| `startup.open_default_window`    | bool   | `false` | Open one terminal automatically when a session starts empty                                                                                                                                |
| `startup.session`                | string | empty   | Session a bare "tuios" attaches to. tuios makes it when it is gone, as tuios attach NAME -c does. Empty attaches to the most recent session.                                               |
| `startup.start_in_terminal_mode` | bool   | `false` | Start focused in terminal mode, when a window is present                                                                                                                                   |
| `startup.tiled`                  | bool   | `true`  | Start a new session tiled instead of floating. False when the config file has no \[startup] table.                                                                                         |
| `startup.window`                 | string | empty   | Pane, by name or id, that a bare "tuios" focuses in startup.session before it attaches. It needs startup.session. When no pane has that name, the focus does not change.                   |

## tape

| Option                | Type   | Default | Description                                                                                |
| --------------------- | ------ | ------- | ------------------------------------------------------------------------------------------ |
| `tape.auto_review`    | bool   | `false` | Open the review dialog on detection instead of only badging it                             |
| `tape.autorun`        | string | `ask`   | What happens on entering a directory with a project tape Values: `off`, `ask`, `auto`.     |
| `tape.banner_ms`      | int    | `8000`  | Milliseconds the "project tape found" banner stays on screen Range: 1000 to 60000.         |
| `tape.done_linger_ms` | int    | `2000`  | Milliseconds the DONE indicator stays on screen after a tape finishes Range: 500 to 30000. |
| `tape.show_status`    | bool   | `true`  | Show the RUNNING pill and a message while a tape plays                                     |

## workspaces

| Option                             | Type | Default | Description                                                                                                            |
| ---------------------------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `workspaces.new_window_when_empty` | bool | `false` | When you switch to a workspace with no panes, open a new pane there. It starts in the folder of the pane you came from |
| `workspaces.return_when_empty`     | bool | `true`  | When the last pane on the workspace on screen closes, show the workspace you came from. Off shows the splash screen    |

## worktree

| Option                 | Type   | Default | Description                                                                                                                                                                                                                |
| ---------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `worktree.path`        | string | empty   | Where new worktrees go, as a template of {{ repo\_path }}, {{ repo }} and {{ branch }}, with \| slug to make one folder name. A relative path starts at repo\_path. Empty puts them under $XDG\_DATA\_HOME/tuios/worktrees |
| `worktree.setup`       | string | empty   | A shell command to run in every new worktree before the agent starts, such as pnpm i. It runs with sh -c in the worktree, in a window named setup, with no grants. Empty runs nothing                                      |
| `worktree.setup_async` | bool   | `false` | Start the agent at once while the setup runs. A failed setup then keeps the worktree and the branch                                                                                                                        |

## Keys set in the file only

These keys are read from `config.toml` only. `tuios set-config` and the settings page cannot change them.
NAME stands for a name that you choose, such as the name of a host.
The description of a table names its keys.

### workspaces

| Key                     | Type | Default | Description                                                                                                              |
| ----------------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `workspaces.base_index` | int  | `1`     | Number workspaces and their default digit keys from 0 or 1. The daemon's workspace IDs stay one-based. Values: `0`, `1`. |

### keybindings

| Key                           | Type   | Default  | Description                                                                                                                                                                                                                                                           |
| ----------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keybindings.preset`          | string | empty    | The keys of another multiplexer, put over the tuios defaults. Empty is tuios. See KEYBINDINGS.md. Values: `tuios`, `tmux`, `screen`, `zellij`.                                                                                                                        |
| `keybindings.leader_key`      | string | `ctrl+b` | The leader key, which starts the prefix commands. A preset can change it.                                                                                                                                                                                             |
| `keybindings.leader_twice`    | string | `send`   | What the leader does when you press it two times. send sends the leader to the pane in terminal mode. last\_workspace goes back to the last workspace, as in screen. Values: `send`, `last_workspace`.                                                                |
| `keybindings.keyboard_layout` | string | `us`     | The keyboard layout for a key that the terminal does not describe. With us, a binding on opt+shift+7 also matches opt+&. Set other for AZERTY, QWERTZ and other layouts. Values: `us`, `other`.                                                                       |
| `keybindings.option_glyphs`   | string | `auto`   | What a character that the macOS Option key typed does. bind runs the Option binding, type sends the character to the pane, and alt runs the binding only when the terminal also reports Alt. auto reads the layout of the Mac. Values: `auto`, `alt`, `bind`, `type`. |
| `keybindings.lock`            | bool   | `false`  | Give every key to the pane in terminal mode, except the leader. The leader unlocks for one action. The zellij preset sets it.                                                                                                                                         |
| `keybindings.nest_exit_key`   | string | `f12`    | The key that ends nest mode. In nest mode every key goes to the pane, the leader too.                                                                                                                                                                                 |
| `keybindings.repeat`          | list   | built in | The actions that stay armed after the leader, as tmux bind -r does. The same key again runs the action again. An empty list turns repeat off.                                                                                                                         |

### daemon

| Key                         | Type   | Default  | Description                                                                                                                                        |
| --------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daemon.agent_binaries`     | list   | `[]`     | More program names to treat as agents, added to the built-in list.                                                                                 |
| `daemon.single_client`      | bool   | `false`  | Keep one client for each session. Each attach detaches the other clients of the session, as tuios attach -d does.                                  |
| `daemon.ssh_agent`          | string | `off`    | follow gives each session a link to the ssh agent of the client used last. New panes get SSH\_AUTH\_SOCK set to the link. Values: `off`, `follow`. |
| `daemon.display`            | string | `follow` | follow gives the new panes of a daemon with no display the display of the local client. off gives them none. Values: `follow`, `off`.              |
| `daemon.respond_from_shell` | bool   | `false`  | Let tuios respond, run from a shell outside every pane, answer the prompt of an agent. tuios refuses a caller inside a pane either way.            |

### hosts

| Key                            | Type   | Default                                                     | Description                                                                                                                                                                                                     |
| ------------------------------ | ------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hosts.NAME.addr`              | string | required                                                    | The address of the machine: anything ssh accepts, an ssh\_config alias too. tuios ignores and logs a host with no addr, or with one that starts with -.                                                         |
| `hosts.NAME.connect_timeout`   | int    | `10`                                                        | The seconds one dial may take before the host counts as unreachable. 0 uses the default.                                                                                                                        |
| `hosts.NAME.command`           | string | empty                                                       | The tuios binary on the host. Empty finds it on the PATH, at the usual install paths, or through a login shell.                                                                                                 |
| `hosts.NAME.ssh_options`       | list   | `[]`                                                        | More ssh arguments, put before the address. tuios accepts only safe options. -A forwards your ssh agent to the host.                                                                                            |
| `hosts.NAME.repos_root`        | string | empty                                                       | The folder on the host that holds its checkouts, such as \~/src. fan --host, worktree new --host and start-agent look there for a repository by its origin URL.                                                 |
| `hosts.NAME.tailscale_login`   | string | empty                                                       | The origin of a Headscale server that sends the Tailscale SSH check of this host. tuios shows a sign-in link only for the Tailscale origins and this one.                                                       |
| `hosts.NAME.allow`             | list   | `["list", "mail", "open", "write", "files", "transcripts"]` | What the machine may do here over the link. An empty list allows nothing. Unset takes the value of \[hosts."\*"], then the default. Values: `list`, `mail`, `open`, `write`, `respond`, `files`, `transcripts`. |
| `hosts.NAME.hold_mail`         | bool   | `false`                                                     | Hold mail from the machine in the Inbox until you pass it on. Unset takes the value of \[hosts."\*"].                                                                                                           |
| `hosts.NAME.hosted_grace`      | string | `1`                                                         | How long a pane that this machine runs for the other machine waits after the link drops, as a Go duration. 0 ends the pane with the link.                                                                       |
| `hosts.NAME.files_roots`       | list   | the receive folder                                          | The folders the machine may write in, with the files capability. The receive folder is \~/Downloads/tuios, or $XDG\_DOWNLOAD\_DIR/tuios on Linux. An empty list allows only the drop folder.                    |
| `hosts.NAME.files_read_roots`  | list   | not set                                                     | The folders the machine may read. Not set allows every file you can read, apart from the read deny list. A list also allows the folders of files\_roots.                                                        |
| `hosts.NAME.files_min_free`    | string | `1GiB`                                                      | The free space a write must leave on its disk: a whole number with B, KB, MB, GB, TB, KiB, MiB, GiB or TiB. 0 turns the check off.                                                                              |
| `hosts.NAME.files_max_entries` | int    | `20000`                                                     | The most new files and folders the machine may make here in ten minutes. Past it, a copy waits. 0 turns the bound off.                                                                                          |

### tailscale

| Key                 | Type   | Default                    | Description                                                                                                                         |
| ------------------- | ------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `tailscale.enabled` | bool   | `true`                     | Offer the machines of your tailnet as addresses. The list is empty on a machine that is not on a tailnet.                           |
| `tailscale.addr`    | string | `dns`                      | The form of the address: dns for the MagicDNS name, name for the short name, ip for the 100.x address. Values: `dns`, `name`, `ip`. |
| `tailscale.user`    | string | empty                      | The ssh login to put before every address.                                                                                          |
| `tailscale.users`   | map    | none                       | A login for each machine, by its short name. It wins over user.                                                                     |
| `tailscale.os`      | list   | the systems that run tuios | The operating systems to offer. An empty list offers every machine.                                                                 |
| `tailscale.offline` | bool   | `false`                    | Also offer machines that are offline.                                                                                               |
| `tailscale.self`    | bool   | `false`                    | Also offer this machine.                                                                                                            |
| `tailscale.shared`  | bool   | `false`                    | Also offer machines that other people shared into your tailnet.                                                                     |
| `tailscale.include` | list   | `[]`                       | Glob patterns on the short name and the MagicDNS name. Empty offers every machine.                                                  |
| `tailscale.exclude` | list   | `[]`                       | Glob patterns of machines not to offer. exclude wins over include.                                                                  |
| `tailscale.max`     | int    | built in                   | The most machines to offer. 0 uses the default.                                                                                     |
| `tailscale.socket`  | string | empty                      | The path to the tailscaled socket, when it is not in the usual place.                                                               |

### agents

| Key                                     | Type   | Default                    | Description                                                                                                                                                                                      |
| --------------------------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agents.herdr_protocol`                 | string | `always`                   | Which panes learn about the socket for the herdr pane state protocol: always for every pane, agents for a pane that starts such a harness, off for none. Values: `always`, `agents`, `off`.      |
| `agents.host_program_status`            | string | `session`                  | How tuios reports the agent states of its panes to your terminal, with OSC 7501. session sends one record for the session, panes one for each pane. Values: `session`, `panes`, `off`.           |
| `agents.silent_after`                   | string | `1`                        | How long a pane whose hooks reported working may stay silent before it shows as unknown, as a Go duration. 0 or off turns it off.                                                                |
| `agents.approvals.enabled`              | list   | `[]`                       | The harnesses whose permission prompts wait for an answer from the Inbox: claude-code (or claude), opencode, kilo and qwen. Empty turns it off.                                                  |
| `agents.approvals.hold_seconds`         | int    | `120`                      | How long a prompt waits for your answer before the harness asks in its own pane, from 10 to 300 seconds. 0 uses the default.                                                                     |
| `agents.approvals.hold_plans`           | bool   | `true`                     | Also hold a plan that an agent asks you to approve when it leaves plan mode.                                                                                                                     |
| `agents.approvals.risk.builtin`         | bool   | `true`                     | Keep the risk rules that tuios ships.                                                                                                                                                            |
| `agents.approvals.risk.panes_may_allow` | bool   | `false`                    | Let a pane that holds the respond grant allow a call that matched a risk rule. Without it, such a pane may only deny the call.                                                                   |
| `agents.approvals.risk.rule`            | tables | none                       | Your own risk rules, added to the shipped ones. Each has a name, the tools it applies to (empty for every tool) and an RE2 pattern.                                                              |
| `agents.permissions.mode`               | string | `open`                     | open gives a pane started with no grants of its own the admin grant. strict gives it grants. Any other value reads as strict. Values: `open`, `strict`.                                          |
| `agents.permissions.grants`             | list   | `["read", "write", "fan"]` | What such a pane holds under strict. An empty list gives nothing. Add files to let a pane copy files near its work.                                                                              |
| `agents.recap.mode`                     | string | `toast`                    | Where the away recap shows: toast in the dock and the Inbox, inbox only in the Inbox, off only in tuios agent-log --recap. Values: `toast`, `inbox`, `off`.                                      |
| `agents.recap.away`                     | string | `1`                        | How long you must be away from a pane before the dock shows its recap, as a Go duration.                                                                                                         |
| `agents.recap.test_patterns`            | list   | built in                   | The commands that count as a test run in the recap, such as go test and npm test. A list replaces the built-in one.                                                                              |
| `agents.queue.max`                      | int    | `8`                        | The messages that the queue of one pane holds, at most 64. 0 uses the default.                                                                                                                   |
| `agents.mail.wake`                      | bool   | `true`                     | Type one line into an agent at rest that has unread mail, so that it reads the mail.                                                                                                             |
| `agents.mail.questions_to_parent`       | bool   | `true`                     | Send a question from a delegated child agent to its parent by mail first. The Inbox holds it for 10 minutes before it alerts you.                                                                |
| `agents.checkpoints.enabled`            | bool   | `true`                     | Save the git work tree of the pane of an agent each time the agent ends a turn that changed a file.                                                                                              |
| `agents.checkpoints.keep`               | int    | `50`                       | How many checkpoints one pane keeps, at most 1000. 0 uses the default.                                                                                                                           |
| `agents.checkpoints.max_untracked_mb`   | int    | `50`                       | Leave an untracked file larger than this many megabytes out of a checkpoint. A negative value sets no limit.                                                                                     |
| `agents.presets.NAME`                   | table  | none                       | A way to start one kind of agent: tuios start-agent --preset NAME. It names the agent and any of args, add\_dirs, grants, model, effort, permission\_mode, env, after\_ready and ready\_timeout. |

### notify

| Key                             | Type   | Default                  | Description                                                                                                                                     |
| ------------------------------- | ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `notify.enabled`                | bool   | `true`                   | Send notifications to your phone. false turns every notification off. tuios sends nothing without a provider.                                   |
| `notify.web_url`                | string | empty                    | The address of tuios-web. Each notification links to web\_url/inbox?item=ID.                                                                    |
| `notify.content`                | string | `summary`                | summary sends the kind, the pane name and the line that the Inbox shows. title sends only the kind and the session. Values: `summary`, `title`. |
| `notify.quiet_active_seconds`   | int    | `120`                    | Hold a notification while you typed at an attached client in this many seconds. 0 sends at once.                                                |
| `notify.cooldown_seconds`       | int    | `60`                     | The shortest time between two notifications for the same pane and kind.                                                                         |
| `notify.max_per_hour`           | int    | `30`                     | The most notifications in one hour. 0 sets no limit.                                                                                            |
| `notify.allow_http_redirects`   | bool   | `false`                  | Let a provider redirect to a plain http address.                                                                                                |
| `notify.triggers.approval`      | bool   | `true`                   | Notify for a permission prompt that waits for you.                                                                                              |
| `notify.triggers.plan`          | bool   | `true`                   | Notify for a plan to approve.                                                                                                                   |
| `notify.triggers.question`      | bool   | `true`                   | Notify for an agent that asks a question in its pane.                                                                                           |
| `notify.triggers.ask`           | bool   | `true`                   | Notify for tuios ask-human.                                                                                                                     |
| `notify.triggers.mail`          | bool   | `false`                  | Notify for agent mail to you.                                                                                                                   |
| `notify.triggers.errored`       | bool   | `false`                  | Notify for an agent that stopped on an error.                                                                                                   |
| `notify.triggers.finished`      | bool   | `false`                  | Notify for an agent that finished a turn.                                                                                                       |
| `notify.ntfy`                   | table  | none                     | Send with ntfy: url (the topic), priority (1 to 5), and token, token\_env or token\_file.                                                       |
| `notify.pushover`               | table  | none                     | Send with Pushover: user and token, each also as \_env or \_file, and url for a relay.                                                          |
| `notify.webhook`                | table  | none                     | Send a JSON POST to url. token, token\_env or token\_file adds an Authorization: Bearer header.                                                 |
| `notify.webpush.subject`        | string | `https://tuios.dev/push` | The VAPID subject: an https URL or a mailto: address that a push service can use to contact you.                                                |
| `notify.webpush.allow_insecure` | bool   | `false`                  | Let tuios send to a push service on a loopback or private address, by https or http.                                                            |

### dock

| Key                          | Type   | Default                                                                                  | Description                                                                                                                                                                                                                                                                 |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dock.left`                  | list   | `["mode", "workspaces", "trail", "tape"]`                                                | The built-in cells on the left end of the dock, in order. An empty list draws nothing there. A look can set it. Values: `clock`, `copy-help`, `cpu`, `mode`, `notifications`, `ram`, `session`, `session-controls`, `tape`, `trail`, `transfers`, `windows`, `workspaces`.  |
| `dock.center`                | list   | `["windows"]`                                                                            | The built-in cells in the middle of the dock, in order. An empty list draws nothing there. A look can set it. Values: `clock`, `copy-help`, `cpu`, `mode`, `notifications`, `ram`, `session`, `session-controls`, `tape`, `trail`, `transfers`, `windows`, `workspaces`.    |
| `dock.right`                 | list   | `["transfers", "notifications", "copy-help", "cpu", "ram", "clock", "session-controls"]` | The built-in cells on the right end of the dock, in order. An empty list draws nothing there. A look can set it. Values: `clock`, `copy-help`, `cpu`, `mode`, `notifications`, `ram`, `session`, `session-controls`, `tape`, `trail`, `transfers`, `windows`, `workspaces`. |
| `dock.custom.NAME.command`   | string | required                                                                                 | The command of your own dock cell, run with sh -c. The first line of its output is the text of the cell.                                                                                                                                                                    |
| `dock.custom.NAME.refresh`   | string | `once`                                                                                   | When the command runs: once, a duration such as 30s, push (it stays running and each line is an update), or event:TYPE\[,TYPE].                                                                                                                                             |
| `dock.custom.NAME.on-click`  | string | empty                                                                                    | A command to run with sh -c when you click the cell.                                                                                                                                                                                                                        |
| `dock.custom.NAME.max-width` | int    | `24`                                                                                     | The widest the cell may be, in cells. 0 uses the default.                                                                                                                                                                                                                   |
| `dock.custom.NAME.fg`        | string | empty                                                                                    | The text colour of the cell, as #rrggbb.                                                                                                                                                                                                                                    |
| `dock.custom.NAME.bg`        | string | empty                                                                                    | The ground colour of the cell, as #rrggbb.                                                                                                                                                                                                                                  |
| `dock.custom.NAME.bold`      | bool   | `false`                                                                                  | Draw the text of the cell in bold.                                                                                                                                                                                                                                          |
| `dock.custom.NAME.cap_left`  | string | empty                                                                                    | Text drawn before the cell, in the colour of its ground.                                                                                                                                                                                                                    |
| `dock.custom.NAME.cap_right` | string | empty                                                                                    | Text drawn after the cell, in the colour of its ground.                                                                                                                                                                                                                     |
| `dock.session`               | table  | none                                                                                     | The session cell: format, with {session}, {workspace} and {pane} (default {session} {workspace}:{pane}), and fg, bg, bold, cap\_left and cap\_right as a custom cell has them.                                                                                              |
| `dock.tabs.style`            | string | empty                                                                                    | How the workspace strip draws its tabs: pill, or flat for coloured runs of text. A look can set it. Values: `pill`, `flat`.                                                                                                                                                 |
| `dock.tabs.separator`        | string | empty                                                                                    | Text between two flat tabs. Empty is one blank column. A look can set it.                                                                                                                                                                                                   |
| `dock.tabs.separator_fg`     | string | empty                                                                                    | Colour of the text between two flat tabs. A look can set it.                                                                                                                                                                                                                |
| `dock.tabs.active_fg`        | string | empty                                                                                    | Text colour of the tab of the current workspace. A look can set it.                                                                                                                                                                                                         |
| `dock.tabs.active_bg`        | string | empty                                                                                    | Background colour of the tab of the current workspace. A look can set it.                                                                                                                                                                                                   |
| `dock.tabs.active_bold`      | bool   | `false`                                                                                  | Draw the flat tab of the current workspace in bold. A pill is always bold. A look can set it.                                                                                                                                                                               |
| `dock.tabs.active_underline` | bool   | empty                                                                                    | Underline the tab of the current workspace. Unset underlines a pill and not a flat tab. A look can set it.                                                                                                                                                                  |
| `dock.tabs.inactive_fg`      | string | empty                                                                                    | Text colour of the tabs of the other workspaces. A look can set it.                                                                                                                                                                                                         |
| `dock.tabs.inactive_bg`      | string | empty                                                                                    | Background colour of the tabs of the other workspaces. A look can set it.                                                                                                                                                                                                   |
| `dock.tabs.inactive_bold`    | bool   | `false`                                                                                  | Draw the tabs of the other workspaces in bold. A look can set it.                                                                                                                                                                                                           |
| `dock.tabs.caps`             | bool   | `false`                                                                                  | Draw rounded ends on each flat tab, in the colour of the tab. A look can set it.                                                                                                                                                                                            |
| `dock.tabs.number_glyphs`    | list   | `[]`                                                                                     | What {icon} in appearance.dock\_workspace\_tab\_format shows for each workspace, the first item for workspace 1. A workspace past the end shows its number. A look can set it.                                                                                              |
| `dock.tabs.zoom_marker`      | string | empty                                                                                    | What {zoom} shows on the tab of the current workspace while a pane in it is zoomed. A look can set it.                                                                                                                                                                      |
| `dock.tabs.show_add`         | bool   | `false`                                                                                  | Keep the + tab in the flat style. A look can set it.                                                                                                                                                                                                                        |
| `dock.tabs.attention_fg`     | string | empty                                                                                    | Text colour of the tab of a workspace with a pane that waits for you. A look can set it.                                                                                                                                                                                    |
| `dock.tabs.bell_marker`      | string | empty                                                                                    | Text after the label of a workspace whose pane rang the bell. Empty shows none. A look can set it.                                                                                                                                                                          |
| `dock.tabs.activity_marker`  | string | empty                                                                                    | Text after the label of a workspace whose pane printed since you looked. Empty shows none. A look can set it.                                                                                                                                                               |

### sidebar

| Key                                 | Type   | Default  | Description                                                                                                                                                                                                    |
| ----------------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance.sidebar.custom.title`   | string | `Custom` | The heading of the custom section of the rail.                                                                                                                                                                 |
| `appearance.sidebar.custom.command` | string | empty    | The command of the custom section, run with sh -c. Each line of its output is a row.                                                                                                                           |
| `appearance.sidebar.custom.refresh` | string | `once`   | When the command runs: once, a duration such as 30s (one second at least), or event:TYPE\[,TYPE]. tuios refuses push.                                                                                          |
| `appearance.sidebar.pane.title`     | string | `pane`   | The heading of the pane section of the rail.                                                                                                                                                                   |
| `appearance.sidebar.pane.command`   | string | empty    | The program that the pane section runs, with sh -c (cmd /C on Windows).                                                                                                                                        |
| `appearance.sidebar.pane.height`    | int    | `0`      | The most rows the pane takes. 0 takes the share of the section in appearance.sidebar.sections, such as pane:30.                                                                                                |
| `appearance.sidebar.left`           | table  | none     | A rail on the left edge, apart from the main rail. Its keys: enabled, width, sections, session, session\_workspace (1 to 9, or 0 for every workspace), custom, and the subagent keys of \[appearance.sidebar]. |
| `appearance.sidebar.right`          | table  | none     | A rail on the right edge, with the same keys as appearance.sidebar.left.                                                                                                                                       |
| `appearance.sidebar.agent_row`      | table  | built in | What an agent row of the rail shows, and the rules that colour its parts. See CONFIGURATION.md.                                                                                                                |

### appearance

| Key                                | Type | Default                     | Description                                                                                           |
| ---------------------------------- | ---- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `appearance.scroll_column_presets` | list | `[33, 50, 55, 67, 90, 100]` | The widths that scroll\_cycle\_width steps through in the scrolling layout, in percent of the screen. |

### notifications

| Key                                      | Type   | Default  | Description                                                |
| ---------------------------------------- | ------ | -------- | ---------------------------------------------------------- |
| `notifications.agent.sounds.done`        | string | built in | A sound file to play when an agent stops.                  |
| `notifications.agent.sounds.needs_input` | string | built in | A sound file to play when an agent waits for you or fails. |

### hints

| Key              | Type | Default | Description                                                                                          |
| ---------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------- |
| `hints.patterns` | list | `[]`    | Your own hint patterns, as Go regular expressions. A group named match sets the part that is copied. |

### links

| Key           | Type   | Default | Description                                                                                                           |
| ------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `links.rules` | tables | none    | Your own links: a regex in Go syntax, and the url a match opens. $0 is the whole match, and $1 or ${name} is a group. |

### files

| Key          | Type   | Default | Description                                                                                                                                                |
| ------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `files.open` | tables | none    | The program that opens a file from the rail: a match glob and a command (a list). The first rule that matches wins. With no match, the system opener runs. |

### tasks

| Key            | Type | Default     | Description                                                                                             |
| -------------- | ---- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `tasks.stages` | list | every stage | The stages that the task board shows. The order stays todo, plan, doing, verify, review, shipped, done. |

### ssh

| Key                     | Type   | Default | Description                                                                                                          |
| ----------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `ssh.handshake_timeout` | string | `2m0s`  | Close a connection that does not log in within this time, as a Go duration. 0 turns it off.                          |
| `ssh.idle_timeout`      | string | `0`     | Close a connection after this time with no traffic in either direction, as a Go duration. 0 turns it off.            |
| `ssh.max_handshakes`    | int    | `32`    | The most connections that may log in at the same time. tuios closes a new connection past it. 0 sets no limit.       |
| `ssh.max_sessions`      | int    | `64`    | The most sessions open at the same time, over all connections. tuios refuses a new session past it. 0 sets no limit. |

### actions and menus

| Key          | Type   | Default | Description                                                                                           |
| ------------ | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `actions`    | tables | none    | Actions of your own: a name, and a label, icon, key, targets, when and trusted. See CONFIGURATION.md. |
| `menus.NAME` | table  | none    | A menu of your own, or a change to a shipped menu: title, sticky, items, add, after and remove.       |

### scratch

| Key               | Type   | Default | Description                                                                                                   |
| ----------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------- |
| `scratch.session` | string | empty   | No longer used. The scratch popup runs a plain shell. tuios names the key when it loads a config that has it. |

### plugins

| Key               | Type | Default | Description                                                                         |
| ----------------- | ---- | ------- | ----------------------------------------------------------------------------------- |
| `plugins.enabled` | list | `[]`    | The ids of the plugins that tuios runs. tuios plugins enable and disable change it. |
| `plugins.dirs`    | list | `[]`    | More plugin folders, or manifests, to list. tuios plugins link adds to it.          |
