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, at the version this site documents.

To filter the options by name, type or value, use the option explorer.

Each option is a key in config.toml. tuios set-config and the settings page change the same options. CONFIGURATION.md tells more about the options that need it. The defaults are the ones on Linux. Some defaults are different on macOS.

agents

OptionTypeDefaultDescription
agents.acp_versionint0The 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_advancebooltrueAfter 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_secondsint120Seconds 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_previewstringautoWhere 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_widthstringemptyThe 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.enabledbooltrueAgents, the Inbox, mail and approvals. Turn off to keep only the multiplexer.
agents.fold_workingboolfalseFold the Working group of the agents view. F folds or opens a group, and the view keeps that choice.
agents.list_widthstringemptyThe 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_hintstringonWhether 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_markersboolfalseAsk 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_rowsint0The 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_secondsint10Seconds after a dismiss, a snooze or a queued reply that u takes it back. 0 uses 10 Range: 0 to 300.
agents.view_liststringcolumnHow 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_mibint8The 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_mibint256The most that the files on one session's task cards take together. 0 uses 256 Range: 0 to 65536.
tasks.attachments_per_cardint20The most attachments one task card holds. 0 uses 20 Range: 0 to 200.
tasks.auto_stagebooltrueMove 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_capint0How 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

OptionTypeDefaultDescription
appearance.alt_dragbooltrueAlt plus left-drag moves a pane
appearance.animation_speedint100Percent window animations run at: 100 as shipped, 200 twice as fast, 50 half as fast Range: 25 to 400.
appearance.animations_enabledbooltrueAnimate 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_focusstringoffType 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.backgroundstringoffBackground 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_colorstringemptyColour 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_terminalstringemptyColour of the focused pane's border in terminal mode. It wins over border_focused_color
appearance.border_focused_color_windowstringemptyColour of the focused pane's border in window mode. It wins over border_focused_color
appearance.border_focused_gradientstringemptyTwo or more colours, separated by spaces or commas, that the focused pane's border steps through. Empty draws one colour
appearance.border_gradient_angleint45Direction 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_stylestringroundedBorder 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_colorstringemptyColour overriding an unfocused pane's border: #585b70, a slot name such as bright_black, or a role such as muted
appearance.calmboolfalseCalm mode: nothing moves or blinks, and only messages that need you show in the dock
appearance.cell_framesstringallWhich 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_msint500Milliseconds 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_typestringdoubleWhat a click on a pane's content does in window-management mode Values: single, double, off.
appearance.confirm_closestringneverWhen 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_quitboolfalseAlways confirm on quit, not only when processes are running --confirm-quit sets it for one run.
appearance.copy_on_selectbooltrueCopy a mouse selection to the clipboard on release
appearance.copy_search_max_matchesint1000Matches 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_backgroundstringemptyBackground 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_foregroundbooltrueLet dim_unfocused dim a pane's text too, not only its background
appearance.dim_multifocusboolfalseDim the panes in the multifocus set like other panes you are not in
appearance.dim_unfocusedint0How much tuios fades a pane you are not in, as a percent. 0 is off. Range: 0 to 90.
appearance.drop_previewstringoutlineWhat 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_delaystring120msHow 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_mouseboolfalseFocus the pane under the cursor as the mouse moves
appearance.focus_follows_mouse_pausestringoffHold this key to keep the focus on the current pane as the mouse moves: off, ctrl, alt Values: off, ctrl, alt.
appearance.focus_wrapboolfalseA focus key at the edge of a tiled layout moves to the pane on the far side
appearance.frame_panelsboolfalseFrame the larger overlay panels, such as the command palette, in the border style
appearance.gapint0Cells of empty ground kept between two neighbouring tiled panes Range: 0 to 8.
appearance.global_sessionbooltrueOffer a session in the rail that holds panes from several machines, once a second one is reachable
appearance.glyphsstringdefaultChrome glyph set: the characters the border, controls, rules and rail marks are drawn with
appearance.hide_scrollbarboolfalseHide the scrollbar thumb on the pane border --hide-scrollbar sets it for one run.
appearance.hide_window_buttonsboolfalseHide the minimize, maximize and close buttons --hide-window-buttons sets it for one run.
appearance.host_titlestringemptyTitle of the terminal tuios runs in, from the focused pane: accepts {title}, {index}, {cwd}, {session} and {workspace}. Empty sets no title
appearance.idle_fpsint10Polls 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_symbolsstringautoDraw 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_placeholdersstringautoDraw images an app positions with kitty Unicode placeholders: auto, on, off Values: auto, on, off.
appearance.link_clickstringbothThe 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_hoverstringsafeThe hover highlight: safe skips a pane whose guest tracks the mouse, always draws it everywhere Values: safe, always.
appearance.link_openerstringemptyThe 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.linksstringallLinks the pointer picks up: off, only marked links (OSC 8), or plain URLs too Values: off, marked, all.
appearance.master_countint1How many panes are master panes in the master-stack layout Range: 1 to 9.
appearance.master_gridbooltrueWith one master on the left, show four or more panes as a grid
appearance.master_positionstringleftSide 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_ratioint50Width of the master pane in the master-stack layout, as a percent of the screen Range: 10 to 90.
appearance.max_fpsint0Highest 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_dimint30How much the screen behind a modal panel is darkened, as a percent. 0 is off. Range: 0 to 90.
appearance.motionstringfullHow 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_dimint45Percent 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_sshboolfalseA split or new window of a pane that runs ssh runs the same ssh
appearance.new_window_inherit_cwdbooltrueA new window starts in the focused pane's working directory
appearance.niri_click_revealsbooltrueIn the scrolling layout, clicking a column that is partly off the edge brings all of it on screen
appearance.niri_hover_revealsbooltrueIn 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_scrollboolfalseReverse the wheel direction in niri scrolling mode
appearance.niri_scroll_cellsint8Cells the scrolling layout's strip moves per mouse wheel event Range: 1 to 200.
appearance.niri_scroll_snapboolfalseSnap the strip to the nearest column when a scroll stops
appearance.nvim_navigationboolfalseLet the Neovim navigator plugin hand terminal focus keys back to TUIOS
appearance.overlay_border_colorstringemptyColour 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_backgroundstringemptyBackground 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_overlaysboolfalseDraw dialogs and panels like pane windows: framed in the focused pane's border colour, on the pane's background
appearance.panel_paddingint2Columns of padding each side of an overlay panel's content Range: 1 to 6.
appearance.paste_previewbooltrueShow a pasted image in a card at the cursor for a few seconds
appearance.paste_preview_msint6000Milliseconds the paste card stays up with nothing pressed Range: 500 to 60000.
appearance.popup_dimint0How 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_shellstringemptyShell that new panes run. Empty picks one for your platform.
appearance.prefix_repeat_timeint500Milliseconds the prefix stays armed after a repeatable command. 0 turns it off. Range: 0 to 5000.
appearance.right_click_opens_menuboolfalseA plain right-click on a pane in terminal mode opens the pane menu, for pasting without selecting first
appearance.scroll_column_maxint90Highest 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_widthint55Width of a column in the scrolling layout, as a percent of the screen Range: 20 to 100.
appearance.scroll_linesint3Lines scrolled per mouse wheel notch Range: 1 to 50.
appearance.scrollback_linesint10000Lines 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_borderboolfalseCarry the session's colour on every pane border, not only on the rail
appearance.session_colorsbooltrueGive each session its own colour on the rail and in the switcher
appearance.shared_bordersboolfalseDraw one border between neighbouring tiled panes, in every layout --shared-borders sets it for one run.
appearance.sidebar_enabledboolfalseShow the session rail Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.enabled
appearance.sidebar_positionstringemptyEdge the session rail sits on Values: left, right, hidden. Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.position
appearance.sidebar_show_countsbooltrueShow the window count on each session row Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.show_counts
appearance.sidebar_show_glyphsbooltrueShow the agent-state glyph on each rail row Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.show_glyphs
appearance.sidebar_show_windowsbooltrueShow the terminals section on the rail Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.show_windows
appearance.sidebar_widthint0Preferred rail width in columns Deprecated: folded into [appearance.sidebar] on load; set appearance.sidebar.width
appearance.themestringemptyColour theme name. Empty follows Omarchy when it is installed, else keeps your terminal's colours. none always keeps them.
appearance.theme_lightstringemptyTheme to use while the terminal is light. Empty uses theme for both. theme is then the dark theme
appearance.theme_transitionstringnoneHow 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_durationint450Milliseconds a theme transition takes at animation speed 100 Range: 100 to 2000.
appearance.tiling_schemestringspiralBSP 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_msint350Milliseconds the pointer rests on a control before its tooltip shows. 0 shows it at once. Range: 0 to 5000.
appearance.whichkey_delay_msint500Milliseconds after the leader key before the which-key panel opens. 0 opens it at once. Range: 0 to 5000.
appearance.whichkey_enabledbooltrueShow the which-key popup after the leader key
appearance.whichkey_positionstringemptyCorner the which-key popup opens in (empty: bottom-right) Values: bottom-right, bottom-left, top-right, top-left, center.
appearance.window_button_positionstringleftWhich end of the title bar the window controls sit on Values: right, left. --window-button-position sets it for one run.
appearance.window_button_stylestringdotsWindow controls as a filled pill or as macOS traffic lights Values: pill, dots. --window-button-style sets it for one run.
appearance.window_button_zoombooltrueCarry the third title bar control on a tiled pane, where it toggles the zoom
appearance.window_chrome_backgroundstringemptyBackground 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_alignstringautoWhere 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_formatstringemptyTitle template accepting {title}, {index} and {cwd}
appearance.window_title_positionstringtopEdge of the pane the title is drawn on Values: bottom, top, hidden. --window-title-position sets it for one run.
appearance.window_title_stylestringpillShape 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_charactersstring@-./_~?&=%+#Punctuation that counts as part of a word for double-click selection
appearance.workspace_transitionstringemptyOld name of motion.workspace Deprecated: folded into motion.workspace on load; set motion.workspace
appearance.workspace_transition_msintemptyOld name of motion.workspace_ms Range: 0 to 1000. Deprecated: folded into motion.workspace_ms on load; set motion.workspace_ms
appearance.wrap_listsbooltrueUp on a list's first row goes to its last, and down on the last goes to the first
appearance.zen_modestringdisabledWhen window borders are hidden: never, always, or while the mouse is idle Values: disabled, always, mouse.
appearance.zen_reveal_msint2000Milliseconds the pointer sits still before zen mode (mouse) hides the borders again Range: 200 to 30000.
appearance.zoom_animationboolemptyOld name of motion.zoom Deprecated: folded into motion.zoom on load; set motion.zoom
appearance.zoom_borderlessboolfalseShow 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_focusbooltrueHand the zoom to the pane the focus lands on, so moving focus while zoomed shows the pane you moved to
appearance.zoom_max_widthint0Width in cells of a zoomed pane. 0 fills the screen. --zoom-max-width sets it for one run.
appearance.zoom_sizeint95How 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.integrationstringautoTurn 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.loginboolfalseStart 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

OptionTypeDefaultDescription
appearance.clock_formatstring15:04Go time layout the clock is drawn with, e.g. 15:04 or Mon 3:04PM
appearance.dock_backgroundstringemptyBackground under the dock: off, theme, or a colour (#rrggbb, 0-255, a slot name or a role name); empty follows appearance.background
appearance.dock_compactboolfalseDraw the dock as one row with no rule. The panes get one more row
appearance.dock_mode_icon_terminalstringdefaultIcon 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_tilingstringdefaultIcon 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_windowstringdefaultIcon in the mode pill in window mode. An empty value shows no icon. default uses the icon of the glyph set
appearance.dock_mode_pillstringtilingWhat 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_letterbooltrueShow V or H after the tiling icon in the mode pill. The letter is the direction of the next split
appearance.dock_pill_capsbooltrueDraw rounded caps on every dock pill: the mode chip, the workspace tabs and the minimized windows. Off draws flat pills
appearance.dock_prefix_indicatorstringpillWhere the dock shows an armed leader key: pill colours the mode pill, badge draws a separate badge Values: pill, badge.
appearance.dock_workspace_label_maxint12Cells 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_formatstringemptyWorkspace tab template accepting {index}, {name}, {icon} and {zoom} (empty: {name}). With {index} in it, an unnamed workspace shows only its number
appearance.dock_workspace_tabsbooltrueShow the clickable workspace strip in the dock
appearance.dock_workspace_tooltipbooltrueShow the workspace name on hover when the pill cuts the name or does not show it
appearance.dockbar_positionstringtopEdge the dock sits on, or hidden Values: bottom, top, hidden. --dockbar-position sets it for one run.
appearance.hide_clockboolfalseHide 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_clockboolfalseShow the clock overlay --show-clock sets it for one run.
appearance.show_cpuboolfalseShow the CPU graph in the dock --show-cpu sets it for one run.
appearance.show_ramboolfalseShow RAM usage in the dock --show-ram sets it for one run.
dock.clock.formatstringemptyGo time layout the clock renders in (empty means 15:04); a layout without seconds refreshes once a minute
dock.meter_interval_msint2000Milliseconds between measurements of the dock's CPU and RAM readouts Range: 500 to 60000.
OptionTypeDefaultDescription
appearance.git_dirtybooltrueCount 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_foldstring1hHow 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.backgroundstringemptyBackground 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_backgroundstringemptyBackground 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.densitystringnormalSpace 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.editorstringemptyThe terminal editor that opens a text file. If this is empty, tuios uses $EDITOR, then $VISUAL, then vi.
appearance.sidebar.enabledbooltrueShow the session rail
appearance.sidebar.file_actionsbooltrueLet the files section create, rename, delete, copy and paste
appearance.sidebar.file_deletestringtrashWhere a delete sends the file: the trash, or nowhere Values: trash, permanent.
appearance.sidebar.file_dragbooltrueDrag a row of the files section into a pane to paste its path
appearance.sidebar.file_icon_colorsbooltrueDraw each file icon in its file type's own colour
appearance.sidebar.file_iconsbooltrueDraw a nerd font icon per file type in the files section
appearance.sidebar.files_stylestringlistHow 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_clickstringnavigateWhat a click on a folder row does Values: navigate, cd, both.
appearance.sidebar.git_refresh_msint2000Milliseconds 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_mainboolfalseGive 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_casestringlowercaseHow the rail's section headers read: lowercase keeps the quiet furniture look, uppercase draws them as headings Values: lowercase, uppercase.
appearance.sidebar.header_stylestringautoHow 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.marqueebooltrueScroll a hovered row's overflowing title
appearance.sidebar.marquee_pause_msint900Milliseconds a hovered row holds still before its overflowing title starts to move. 0 starts at once Range: 0 to 10000.
appearance.sidebar.marquee_step_msint220Milliseconds each one-cell step of the rail's marquee is held. Larger is slower. Range: 20 to 2000.
appearance.sidebar.peekbooltrueShow a session's panes in the terminals section while the pointer or the rail cursor is on its row
appearance.sidebar.per_sessionboolfalseEach session keeps its own shown or hidden rail. Off, showing or hiding the rail applies to every session
appearance.sidebar.positionstringrightEdge the rail sits on, or hidden Values: left, right, hidden.
appearance.sidebar.row_stylestringbarHow the rail marks the row you are on: bar in the gutter, marker glyph, underline, or pill Values: bar, marker, underline, pill.
appearance.sidebar.sectionsstringsessions:25,terminals,files:25,agents:34Section 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_agentsbooltrueShow 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_countsbooltrueShow the window count on each session row
appearance.sidebar.show_glyphsbooltrueShow the agent-state glyph on each row
appearance.sidebar.show_numbersboolfalseShow the switch number ahead of each session name
appearance.sidebar.show_windowsbooltrueShow the terminals section Deprecated: folded into appearance.sidebar.sections on load; leave terminals out of the layout
appearance.sidebar.subagent_collapsestringoffA 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_fieldsstringmark,name,time,noteWhat 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_finishedstringoffHow 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_rowsint0The most lines one agent's subagents take, the +N more line included. 0 is no limit. Range: 0 to 16.
appearance.sidebar.subagent_rowsstringrowsHow 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.tooltipsbooltrueLabel the collapsed strip on hover
appearance.sidebar.widthint24Preferred rail width in columns on a wide screen
appearance.sidebar.workspacesstringemptyWorkspace 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

OptionTypeDefaultDescription
appearance.scrollbar.stylestringtrackHairline thumb over the content column, or a full-height track Values: thin, track.
appearance.scrollbar.thumbstringemptyOne-cell glyph for the thumb. Empty uses the style's own.
appearance.scrollbar.tintstringquietBar colour: quiet, border, muted, or a colour (#rrggbb, 0-255, a slot name or a role name)
appearance.scrollbar.trackstringemptyOne-cell glyph for the track, or none. Empty uses the style's own.

selection

OptionTypeDefaultDescription
appearance.selection.bgstring#45475ABackground behind selected text
appearance.selection.boldboolfalseDraw selected text bold as well as tinted
appearance.selection.copy_commandstringemptyA 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_entrystringcursorWhere copy mode puts its cursor: on the terminal cursor or in the center Values: cursor, center.
appearance.selection.cursor_bgstring#39C5CFBackground of the copy mode cursor block
appearance.selection.cursor_fgstring#08222BText colour under the copy mode cursor. Empty keeps it.
appearance.selection.fgstringemptySelected text colour. Empty keeps the colour it already has.
appearance.selection.flashbooltrueSweep a band of light over text that was just copied. Set motion to none to turn it off.
appearance.selection.flash_colorstringemptyThe light the copy sweep is made of
appearance.selection.flash_msint420Milliseconds one copy sweep takes Range: 80 to 3000.
appearance.selection.flash_stylestringdiagonalThe shape the copy sweep takes Values: diagonal, diagonal-reverse, horizontal, vertical.
appearance.selection.match_bgstring#E5A93DBackground behind the match the cursor is on
appearance.selection.match_fgstring#1C1B19Text colour of the match the cursor is on. Empty keeps it.
appearance.selection.multi_formatstringplainThe format multi copy mode yanks in: plain, markdown or json Values: plain, markdown, json.
appearance.selection.osc52_writestringfocusedWhat 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_bgstring#8A6D2FBackground behind every search match
appearance.selection.search_fgstring#F5E7C8Text colour of a search match. Empty keeps the colour it has.
paste_buffers.limitint20How many yanks to keep to paste again. When it is full, the oldest goes. 0 keeps none. Range: 0 to 1000.
paste_buffers.max_kbint16384Most 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

OptionTypeDefaultDescription
daemon.agent_autodetectbooltrueDetect 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_secondsint2Seconds 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_secondsint30Seconds 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_secondsint30Seconds 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_upgradebooltrueAfter 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_secondsint0Seconds 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_secondsint30Seconds 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_secondsint8Seconds one listing over a live link may take before the link is dialed again. 0 uses 8 Range: 0 to 120.
daemon.host_heartbeat_secondsint15Seconds a link to another machine may carry nothing before the daemon pings it. 0 uses 15 Range: 0 to 300.
daemon.host_heartbeat_timeout_secondsint5Seconds one ping to another machine waits for its reply. Two misses end the link. 0 uses 5 Range: 0 to 60.
daemon.keep_awakestringoffKeep 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_levelstringoffHow much the daemon logs Values: off, errors, basic, messages, verbose, trace.
daemon.persist_scrollbackbooltrueSave each pane's history and show it again after a daemon restart. A change applies when the daemon next starts.
daemon.persist_scrollback_kbint0Most 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_linesint0Most history lines one pane saves. 0 uses 1000. A change applies when the daemon next starts. Range: 0 to 1000000.
daemon.pr_poll_secondsint60Seconds 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_secondsint15Seconds a client waits for a restarted daemon before it gives up. 0 uses 15 Range: 0 to 300.
daemon.resume_agentsstringaskAfter a daemon restart, ask to resume each pane's agent conversation, resume it, or do neither Values: ask, auto, off.
daemon.save_secondsint30Most 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_secondsint60Seconds 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_secondsint1800Seconds 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_sizestringlatestThe 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

OptionTypeDefaultDescription
debug.show_key_countint5How many recent keypresses the showkeys overlay keeps, for a screencast Range: 1 to 20.
debug.show_key_eventsboolfalseShow the on-screen keycast of recent keypresses

files

OptionTypeDefaultDescription
files.drop_keep_hoursint24Hours 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_mbint256Most MiB the drop folder holds. A drop that does not fit is refused. 0 uses 256 Range: 0 to 65536.
files.open_copy_ask_mbint200Above 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_daysint7Days 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_mbint4096Above this size in MiB, o on a file of another machine does not copy it here. 0 uses 4096 Range: 0 to 1048576.

hints

OptionTypeDefaultDescription
hints.all_panesboolfalseThe hints key labels every pane on the workspace, not only the focused pane
hints.alphabetstringasdfghjklLetters the hint labels are made of, easiest first
hints.builtinsstringallBuilt-in patterns hints mode looks for: all, none, or names such as url,path,sha
hints.dimint60Percent of its light the text around the hints loses Range: 10 to 90.
hints.openbooltrueCtrl and a label opens the URL or path. It does not open on a remote client

launcher

OptionTypeDefaultDescription
launcher.gui_commandstringemptyCommand 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_openboolfalseKeep 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

OptionTypeDefaultDescription
mermaid.backgroundstringthemeBackground of a tuios mermaid picture: theme for the theme's colour, or none for the terminal's own background Values: theme, none.
mermaid.themestringtuiosColours of tuios mermaid: tuios for the colours of your theme, or a named theme such as flexoki, nord or rose-pine

motion

OptionTypeDefaultDescription
motion.confettistringonThe confetti burst: on or off. It needs appearance.motion = "full" Values: on, off.
motion.copystringonA sweep crosses the cells a copy took: on or off Values: on, off.
motion.layoutstringonPanes slide when they open, close, split, swap, snap, minimize or restore: on or off Values: on, off.
motion.layout_msint300Milliseconds the layout motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.
motion.overlaysstringonA palette or dialog fades in as it opens: on or off. It needs appearance.motion = "full" and truecolor Values: on, off.
motion.overlays_msint120Milliseconds the overlays motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.
motion.scrollstringonThe scrolling layout slides when the view moves: on or off Values: on, off.
motion.scroll_msint300Milliseconds the scroll motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.
motion.sidebarstringonThe shimmer on a working agent row of the sidebar: on or off. It needs appearance.motion = "full" Values: on, off.
motion.workspacestringslideHow tuios shows a workspace switch: slide, fade or none. With 16 colours, fade is a cut Values: slide, fade, none.
motion.workspace_msint200Milliseconds the workspace motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.
motion.zoomstringonA pane slides between its tile and the zoom box: on or off Values: on, off.
motion.zoom_msint200Milliseconds the zoom motion takes at animation speed 100. 0 is a cut. Range: 0 to 1000.

mouse

OptionTypeDefaultDescription
mouse.double_click_msint300Milliseconds 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_thresholdint5Cells 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

OptionTypeDefaultDescription
notifications.agent.commandstringemptyShell command to run on an alert. Empty runs nothing.
notifications.agent.dockbooltrueShow the alert in the dock. Click it to go to the pane.
notifications.agent.enabledbooltrueTurn every agent alert on or off
notifications.agent.notifybooltrueSend a desktop notification to the attached terminal
notifications.agent.quiet_hoursstringemptyHours when nothing alerts. Write it as HH:MM-HH:MM.
notifications.agent.settle_secondsint2Seconds to wait. tuios drops the alert if the pane changes state. Range: 0 to 3600.
notifications.agent.soundboolfalseMake an alert audible
notifications.agent.sound_cooldown_secondsint3Shortest gap between two sounds, in seconds. 0 uses 3. Range: 0 to 3600.
notifications.agent.sound_modestringemptyHow an alert sounds: a cue, a BEL, or both Values: audio, bell, both.
notifications.agent.states.donebooltrueAlert when an agent reports it finished
notifications.agent.states.erroredbooltrueAlert when an agent stops on an error
notifications.agent.states.idleboolfalseAlert when an agent goes quiet
notifications.agent.states.needs_inputbooltrueAlert when an agent waits for you
notifications.agent.states.workingboolfalseAlert when an agent starts work
notifications.agent.suppress_focusedbooltrueNo alert for the focused pane while the terminal has focus
notifications.bellstringtoastWhat 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_msint200Milliseconds in which a second bell from a pane is dropped. 0 keeps every one. Range: 0 to 10000.
notifications.durationint0Seconds an info message stays up. 0 uses the default, 2. Range: 0 to 3600.
notifications.error_durationint0Seconds an error stays up when error_sticky is false. 0 uses the default, 15. Range: 0 to 3600.
notifications.error_stickybooltrueMake errors wait for esc instead of expiring
notifications.levelstringinfoThe 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_hiddenbooltruePut messages below notifications.level in the log viewer. When off, they go nowhere. Warnings and errors always go to the log
notifications.machine_offerbooltrueOffer to add a machine when a pane logs in to it with ssh or mosh and no [hosts] entry reaches it
notifications.mail.between_agentsboolfalseAlert on a message from one agent to another agent too.
notifications.mail.dockboolfollows notifications.agent.dockShow a mail alert in the dock. Unset follows notifications.agent.dock.
notifications.mail.enabledboolfollows notifications.agent.enabledTurn mail alerts on or off. Unset follows notifications.agent.enabled.
notifications.mail.notifyboolfollows notifications.agent.notifySend a desktop notification for mail. Unset follows notifications.agent.notify.
notifications.mail.soundboolfollows notifications.agent.soundMake a mail alert audible. Unset follows notifications.agent.sound.
notifications.rate_limit_msint500Milliseconds in which a second desktop notification from a pane is dropped. 0 keeps every one. Range: 0 to 10000.
notifications.stylestringfullHow 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_durationint0Seconds a warning stays up. 0 uses the default, 8. Range: 0 to 3600.

panes

OptionTypeDefaultDescription
panes.drag_and_dropboolfalseDrag and drop between panes over the kitty drag and drop protocol (OSC 72)
panes.drag_and_drop_desktopboolfalseBridge drags to and from the desktop through a terminal that speaks the protocol (kitty)
panes.label_keysstring1234567890Keys the pane labels are made of, first pane first. Letters a to z and digits
panes.navigator_layoutstringtreeHow the pane navigator lists the panes when it opens Values: tree, flat, cards.
panes.navigator_searchboolfalseOpen the pane navigator ready to type a search
path_picker.show_hiddenboolfalseThe path picker lists hidden files. Alt+h in the picker shows or hides them

pip

OptionTypeDefaultDescription
pip.cornerstringbottom-rightCorner 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.heightint12Height of the picture-in-picture view, border included, in cells Range: 3 to 100.
pip.widthint40Width of the picture-in-picture view, border included, in cells Range: 12 to 200.

review

OptionTypeDefaultDescription
review.focusstringdiffWhich side of the review overlay has the keys when a review opens: the diff or the file list Values: diff, files.
review.scopestringbaseWhat a review shows when it opens: the changes since the base, or only the uncommitted changes. u switches between them Values: base, uncommitted.

scratch

OptionTypeDefaultDescription
scratch.heightstring80%Height of the scratch terminal, in cells (20) or percent (80%)
scratch.widthstring80%Width of the scratch terminal, in cells (60) or percent (80%)

screensaver

OptionTypeDefaultDescription
screensaver.effectstringrandomWhich 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.enabledboolfalseAnimate the screen after a spell with no input
screensaver.idle_minutesint10Minutes of quiet before the screen saver starts Range: 1 to 240.
screensaver.while_busyboolfalseStart even when a pane is running a command or an agent

screenshot

OptionTypeDefaultDescription
screenshot.backgroundstringautoWash behind the card: auto derives it from the theme; none, a hex color, or hex..hex work too
screenshot.controlsstringautoWindow control marks: the macOS lights, your glyph set, or none Values: auto, macos, glyphs, none.
screenshot.copybooltrueTry to copy the capture to the clipboard
screenshot.cursorboolfalseDraw the cursor cell in the capture
screenshot.directorystring~/Pictures/tuiosFolder where capture files are saved
screenshot.font_familystringJetBrains Mono, monospaceFont to draw the capture in when your terminal does not say which it uses
screenshot.font_filestringemptyFont file to draw PNG with, also embedded in SVG and HTML. It wins over every other font choice.
screenshot.formatstringpngDefault output format for captures Values: png, svg, ansi, html, txt.
screenshot.framestringwindowDressing around the capture: a window card, a plain card, or nothing Values: window, plain, none.
screenshot.paddingint48Space around the card in pixels Range: 0 to 128.
screenshot.previewbooltrueOpen the preview panel after a capture
screenshot.radiusint10Card corner radius in pixels Range: 0 to 32.
screenshot.scaleint2PNG size multiplier Range: 1 to 4.
screenshot.shadowbooltrueDraw a soft shadow under the card
screenshot.title_formatstring{title}Title bar text of a screenshot: {title} (the window title as its title bar shows it), {index} and {cwd}

spotlight

OptionTypeDefaultDescription
spotlight.dimint75Percent of its light an unlit cell loses Range: 10 to 95.
spotlight.edgestringhardCut 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.enabledboolfalseLight one part of the screen and dim the rest
spotlight.followstringmouseWhat the beam follows: the mouse, or the focused pane's cursor. The cursor sends fewer bytes to a remote client Values: cursor, mouse.
spotlight.radiusint10Half the beam's height, in rows Range: 2 to 200.
spotlight.shakeboolfalseMove 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

OptionTypeDefaultDescription
startup.daemonbooltrueMake 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.layoutstringbspTiling scheme a new session starts in. An existing session keeps its own. Values: bsp, master-stack, scrolling.
startup.open_default_windowboolfalseOpen one terminal automatically when a session starts empty
startup.sessionstringemptySession 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_modeboolfalseStart focused in terminal mode, when a window is present
startup.tiledbooltrueStart a new session tiled instead of floating. False when the config file has no [startup] table.
startup.windowstringemptyPane, 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

OptionTypeDefaultDescription
tape.auto_reviewboolfalseOpen the review dialog on detection instead of only badging it
tape.autorunstringaskWhat happens on entering a directory with a project tape Values: off, ask, auto.
tape.banner_msint8000Milliseconds the "project tape found" banner stays on screen Range: 1000 to 60000.
tape.done_linger_msint2000Milliseconds the DONE indicator stays on screen after a tape finishes Range: 500 to 30000.
tape.show_statusbooltrueShow the RUNNING pill and a message while a tape plays

workspaces

OptionTypeDefaultDescription
workspaces.new_window_when_emptyboolfalseWhen 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_emptybooltrueWhen the last pane on the workspace on screen closes, show the workspace you came from. Off shows the splash screen

worktree

OptionTypeDefaultDescription
worktree.pathstringemptyWhere 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.setupstringemptyA 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_asyncboolfalseStart 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

KeyTypeDefaultDescription
workspaces.base_indexint1Number workspaces and their default digit keys from 0 or 1. The daemon's workspace IDs stay one-based. Values: 0, 1.

keybindings

KeyTypeDefaultDescription
keybindings.presetstringemptyThe keys of another multiplexer, put over the tuios defaults. Empty is tuios. See KEYBINDINGS.md. Values: tuios, tmux, screen, zellij.
keybindings.leader_keystringctrl+bThe leader key, which starts the prefix commands. A preset can change it.
keybindings.leader_twicestringsendWhat 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_layoutstringusThe 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_glyphsstringautoWhat 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.lockboolfalseGive 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_keystringf12The key that ends nest mode. In nest mode every key goes to the pane, the leader too.
keybindings.repeatlistbuilt inThe 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

KeyTypeDefaultDescription
daemon.agent_binarieslist[]More program names to treat as agents, added to the built-in list.
daemon.single_clientboolfalseKeep one client for each session. Each attach detaches the other clients of the session, as tuios attach -d does.
daemon.ssh_agentstringofffollow 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.displaystringfollowfollow 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_shellboolfalseLet 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

KeyTypeDefaultDescription
hosts.NAME.addrstringrequiredThe 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_timeoutint10The seconds one dial may take before the host counts as unreachable. 0 uses the default.
hosts.NAME.commandstringemptyThe tuios binary on the host. Empty finds it on the PATH, at the usual install paths, or through a login shell.
hosts.NAME.ssh_optionslist[]More ssh arguments, put before the address. tuios accepts only safe options. -A forwards your ssh agent to the host.
hosts.NAME.repos_rootstringemptyThe 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_loginstringemptyThe 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.allowlist["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_mailboolfalseHold mail from the machine in the Inbox until you pass it on. Unset takes the value of [hosts."*"].
hosts.NAME.hosted_gracestring1How 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_rootslistthe receive folderThe 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_rootslistnot setThe 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_freestring1GiBThe 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_entriesint20000The most new files and folders the machine may make here in ten minutes. Past it, a copy waits. 0 turns the bound off.

tailscale

KeyTypeDefaultDescription
tailscale.enabledbooltrueOffer the machines of your tailnet as addresses. The list is empty on a machine that is not on a tailnet.
tailscale.addrstringdnsThe 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.userstringemptyThe ssh login to put before every address.
tailscale.usersmapnoneA login for each machine, by its short name. It wins over user.
tailscale.oslistthe systems that run tuiosThe operating systems to offer. An empty list offers every machine.
tailscale.offlineboolfalseAlso offer machines that are offline.
tailscale.selfboolfalseAlso offer this machine.
tailscale.sharedboolfalseAlso offer machines that other people shared into your tailnet.
tailscale.includelist[]Glob patterns on the short name and the MagicDNS name. Empty offers every machine.
tailscale.excludelist[]Glob patterns of machines not to offer. exclude wins over include.
tailscale.maxintbuilt inThe most machines to offer. 0 uses the default.
tailscale.socketstringemptyThe path to the tailscaled socket, when it is not in the usual place.

agents

KeyTypeDefaultDescription
agents.herdr_protocolstringalwaysWhich 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_statusstringsessionHow 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_afterstring1How 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.enabledlist[]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_secondsint120How 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_plansbooltrueAlso hold a plan that an agent asks you to approve when it leaves plan mode.
agents.approvals.risk.builtinbooltrueKeep the risk rules that tuios ships.
agents.approvals.risk.panes_may_allowboolfalseLet 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.ruletablesnoneYour 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.modestringopenopen 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.grantslist["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.modestringtoastWhere 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.awaystring1How long you must be away from a pane before the dock shows its recap, as a Go duration.
agents.recap.test_patternslistbuilt inThe 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.maxint8The messages that the queue of one pane holds, at most 64. 0 uses the default.
agents.mail.wakebooltrueType one line into an agent at rest that has unread mail, so that it reads the mail.
agents.mail.questions_to_parentbooltrueSend 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.enabledbooltrueSave the git work tree of the pane of an agent each time the agent ends a turn that changed a file.
agents.checkpoints.keepint50How many checkpoints one pane keeps, at most 1000. 0 uses the default.
agents.checkpoints.max_untracked_mbint50Leave an untracked file larger than this many megabytes out of a checkpoint. A negative value sets no limit.
agents.presets.NAMEtablenoneA 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

KeyTypeDefaultDescription
notify.enabledbooltrueSend notifications to your phone. false turns every notification off. tuios sends nothing without a provider.
notify.web_urlstringemptyThe address of tuios-web. Each notification links to web_url/inbox?item=ID.
notify.contentstringsummarysummary 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_secondsint120Hold a notification while you typed at an attached client in this many seconds. 0 sends at once.
notify.cooldown_secondsint60The shortest time between two notifications for the same pane and kind.
notify.max_per_hourint30The most notifications in one hour. 0 sets no limit.
notify.allow_http_redirectsboolfalseLet a provider redirect to a plain http address.
notify.triggers.approvalbooltrueNotify for a permission prompt that waits for you.
notify.triggers.planbooltrueNotify for a plan to approve.
notify.triggers.questionbooltrueNotify for an agent that asks a question in its pane.
notify.triggers.askbooltrueNotify for tuios ask-human.
notify.triggers.mailboolfalseNotify for agent mail to you.
notify.triggers.erroredboolfalseNotify for an agent that stopped on an error.
notify.triggers.finishedboolfalseNotify for an agent that finished a turn.
notify.ntfytablenoneSend with ntfy: url (the topic), priority (1 to 5), and token, token_env or token_file.
notify.pushovertablenoneSend with Pushover: user and token, each also as _env or _file, and url for a relay.
notify.webhooktablenoneSend a JSON POST to url. token, token_env or token_file adds an Authorization: Bearer header.
notify.webpush.subjectstringhttps://tuios.dev/pushThe VAPID subject: an https URL or a mailto: address that a push service can use to contact you.
notify.webpush.allow_insecureboolfalseLet tuios send to a push service on a loopback or private address, by https or http.

dock

KeyTypeDefaultDescription
dock.leftlist["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.centerlist["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.rightlist["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.commandstringrequiredThe 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.refreshstringonceWhen 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-clickstringemptyA command to run with sh -c when you click the cell.
dock.custom.NAME.max-widthint24The widest the cell may be, in cells. 0 uses the default.
dock.custom.NAME.fgstringemptyThe text colour of the cell, as #rrggbb.
dock.custom.NAME.bgstringemptyThe ground colour of the cell, as #rrggbb.
dock.custom.NAME.boldboolfalseDraw the text of the cell in bold.
dock.custom.NAME.cap_leftstringemptyText drawn before the cell, in the colour of its ground.
dock.custom.NAME.cap_rightstringemptyText drawn after the cell, in the colour of its ground.
dock.sessiontablenoneThe 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.stylestringemptyHow the workspace strip draws its tabs: pill, or flat for coloured runs of text. A look can set it. Values: pill, flat.
dock.tabs.separatorstringemptyText between two flat tabs. Empty is one blank column. A look can set it.
dock.tabs.separator_fgstringemptyColour of the text between two flat tabs. A look can set it.
dock.tabs.active_fgstringemptyText colour of the tab of the current workspace. A look can set it.
dock.tabs.active_bgstringemptyBackground colour of the tab of the current workspace. A look can set it.
dock.tabs.active_boldboolfalseDraw the flat tab of the current workspace in bold. A pill is always bold. A look can set it.
dock.tabs.active_underlineboolemptyUnderline the tab of the current workspace. Unset underlines a pill and not a flat tab. A look can set it.
dock.tabs.inactive_fgstringemptyText colour of the tabs of the other workspaces. A look can set it.
dock.tabs.inactive_bgstringemptyBackground colour of the tabs of the other workspaces. A look can set it.
dock.tabs.inactive_boldboolfalseDraw the tabs of the other workspaces in bold. A look can set it.
dock.tabs.capsboolfalseDraw rounded ends on each flat tab, in the colour of the tab. A look can set it.
dock.tabs.number_glyphslist[]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_markerstringemptyWhat {zoom} shows on the tab of the current workspace while a pane in it is zoomed. A look can set it.
dock.tabs.show_addboolfalseKeep the + tab in the flat style. A look can set it.
dock.tabs.attention_fgstringemptyText colour of the tab of a workspace with a pane that waits for you. A look can set it.
dock.tabs.bell_markerstringemptyText after the label of a workspace whose pane rang the bell. Empty shows none. A look can set it.
dock.tabs.activity_markerstringemptyText after the label of a workspace whose pane printed since you looked. Empty shows none. A look can set it.
KeyTypeDefaultDescription
appearance.sidebar.custom.titlestringCustomThe heading of the custom section of the rail.
appearance.sidebar.custom.commandstringemptyThe command of the custom section, run with sh -c. Each line of its output is a row.
appearance.sidebar.custom.refreshstringonceWhen the command runs: once, a duration such as 30s (one second at least), or event:TYPE[,TYPE]. tuios refuses push.
appearance.sidebar.pane.titlestringpaneThe heading of the pane section of the rail.
appearance.sidebar.pane.commandstringemptyThe program that the pane section runs, with sh -c (cmd /C on Windows).
appearance.sidebar.pane.heightint0The most rows the pane takes. 0 takes the share of the section in appearance.sidebar.sections, such as pane:30.
appearance.sidebar.lefttablenoneA 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.righttablenoneA rail on the right edge, with the same keys as appearance.sidebar.left.
appearance.sidebar.agent_rowtablebuilt inWhat an agent row of the rail shows, and the rules that colour its parts. See CONFIGURATION.md.

appearance

KeyTypeDefaultDescription
appearance.scroll_column_presetslist[33, 50, 55, 67, 90, 100]The widths that scroll_cycle_width steps through in the scrolling layout, in percent of the screen.

notifications

KeyTypeDefaultDescription
notifications.agent.sounds.donestringbuilt inA sound file to play when an agent stops.
notifications.agent.sounds.needs_inputstringbuilt inA sound file to play when an agent waits for you or fails.

hints

KeyTypeDefaultDescription
hints.patternslist[]Your own hint patterns, as Go regular expressions. A group named match sets the part that is copied.
KeyTypeDefaultDescription
links.rulestablesnoneYour 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

KeyTypeDefaultDescription
files.opentablesnoneThe 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

KeyTypeDefaultDescription
tasks.stageslistevery stageThe stages that the task board shows. The order stays todo, plan, doing, verify, review, shipped, done.

ssh

KeyTypeDefaultDescription
ssh.handshake_timeoutstring2m0sClose a connection that does not log in within this time, as a Go duration. 0 turns it off.
ssh.idle_timeoutstring0Close a connection after this time with no traffic in either direction, as a Go duration. 0 turns it off.
ssh.max_handshakesint32The most connections that may log in at the same time. tuios closes a new connection past it. 0 sets no limit.
ssh.max_sessionsint64The most sessions open at the same time, over all connections. tuios refuses a new session past it. 0 sets no limit.

actions and menus

KeyTypeDefaultDescription
actionstablesnoneActions of your own: a name, and a label, icon, key, targets, when and trusted. See CONFIGURATION.md.
menus.NAMEtablenoneA menu of your own, or a change to a shipped menu: title, sticky, items, add, after and remove.

scratch

KeyTypeDefaultDescription
scratch.sessionstringemptyNo longer used. The scratch popup runs a plain shell. tuios names the key when it loads a config that has it.

plugins

KeyTypeDefaultDescription
plugins.enabledlist[]The ids of the plugins that tuios runs. tuios plugins enable and disable change it.
plugins.dirslist[]More plugin folders, or manifests, to list. tuios plugins link adds to it.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page