Configuration

The dock and the session rail

The dock and the session rail: part of the Configuration of TUIOS.

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

The dock's components

The [dock] table's region lists and custom components are not scalar options, so list-options does not carry them; of the table it carries only dock.clock.format. The settings page edits them through an editor of its own rather than a row: Dock → Components, where the three regions and what is in them are one list. Shifted arrows move a component and carry it into the next region off the end of its own, Enter takes one off the bar or puts it back, u undoes the session's edits and r restores the defaults. It is three ordered lists of component names, plus a table per custom component:

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

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

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

The lists above are the default: omit the whole table and the bar is unchanged.

The clock draws hours and minutes (15:04) unless dock.clock.format or appearance.clock_format sets another Go time layout. To show seconds, set format = "15:04:05". A clock with seconds draws a frame every second. A clock without seconds draws one frame a minute. When the center list has a clock or a custom cell, the center is at the middle of the terminal. A notification does not move it or shorten its minimized pane labels. On a crowded bar, the center moves left to keep the right-hand cells on the screen. Click a cut notification to read the full message. transfers shows the copies between machines. It shows nothing while no copy exists. One copy is a bar and a percent, [####--] 61%. More copies are a count and a percent, 3 copies 42%. waiting means a link is down, and 1 failed stays until you open the Copies panel. A click opens the panel. Add transfers to your own right list to see it there. session shows the session name, workspace and pane, main 2:1, and is in no default list. [dock.session] takes format ({session}, {workspace}, {pane}) and the cell style keys fg, bg, bold, cap_left and cap_right, which [dock.custom.NAME] takes too. Colours take any colour value. A custom component's first line of stdout becomes its cell, it is hidden when the command fails, and tuios list-dock-components says which and why. The command and the on-click command get TUIOS_SESSION, TUIOS_SOCKET and TUIOS_DOCK_COMPONENT, the name of the component. The on-click command also gets TUIOS_CLICK_BUTTON, the mouse button: 1 for left, 2 for middle and 3 for right. tuios runs one copy of the command at a time. When an event arrives while the command runs, tuios runs the command one more time when it ends. An interval that comes due while the command runs is skipped.

Workspace tab style

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

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

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

Colours take any colour value. The colours are overrides: a flat strip with none set puts the current tab on the theme's accent, in bold, and draws the others in dim text on the bar's own ground, so it still shows where you are. A value that is not a colour is ignored, with a warning, as if it were unset.

The four tab colours (active_fg, active_bg, inactive_fg, inactive_bg) and inactive_bold also apply to pills. A pill with no colour set keeps the theme's look. The current pill is always bold, so active_bold is for flat tabs only.

active_underline underlines the tab of the current workspace. When it is not set, a pill is underlined and a flat tab is not.

caps = true gives each flat tab the rounded ends of a pill. Each end has the colour of its tab's background. A tab with no background gets a blank column in place of each end, so the tabs keep their width. The ends use the pills' glyphs: there are none under ASCII glyphs or with appearance.dock_pill_caps = false. Pills always have ends, so caps with the pill style gives a warning.

Flat tabs with your own colours and rounded ends:

[dock.tabs]
style       = "flat"
caps        = true
active_bg   = "magenta"
active_fg   = "bg"
active_bold = true
inactive_bg = "bright_black"
inactive_fg = "fg"

Pills with your own colours and no underline:

[dock.tabs]
active_bg        = "magenta"
active_fg        = "bg"
inactive_bg      = "bright_black"
active_underline = false

Besides {index} and {name}, the tab format takes {icon} and {zoom}. {name} is the name you gave the workspace. A workspace you did not name shows the name its active pane gave with OSC 1. The active pane is the focused one, or the one that had the focus last. Only OSC 1 counts: shells and agents set the window title with OSC 0 at every prompt, and that title stays on the pane's border. A program names its workspace with printf '\033]1;logs\007' and clears the name with an empty OSC 1. A workspace with neither name has an empty {name} when the format has {index}, and the separator next to it (spaces, :, -, · or |) is dropped with it, so "{index} {name}" shows 7 for such a workspace and 7 api for one named api. In a format without {index}, such as the default {name}, its {name} is its number. {index} is the workspace's number, which is its position: dragging a tab to another place, or moving the workspace with move_workspace_left and move_workspace_right, renumbers it, and Alt+N goes to it by its new number. The flat style shows even a lone workspace and drops the + tab unless show_add is on. With no [dock.tabs] table the strip is unchanged.

Tab marks

Three more keys mark a workspace you are not looking at, in the pill style and the flat style:

[dock.tabs]
attention_fg    = "warning"   # the tab's ink while a pane on it waits for you
bell_marker     = "!"         # after the label when a pane on it rang the bell
activity_marker = "#"         # after the label when a pane on it printed
  • attention_fg is the ink of the tab while an agent on that workspace asks for input or stopped on an error. It takes any colour value.
  • bell_marker and activity_marker go after the label, after the label cap. The bell marker comes first.
  • A mark stays until you look at the workspace.
  • The current workspace's tab never carries them.
  • With a key empty, tuios draws nothing for it and keeps no record.
  • Attached to a daemon, the marks need a daemon of this version or newer. An older daemon does not report a pane on another workspace, so its tab gets no bell or activity mark.

examples/dock/README.md is the full contract and five working recipes.

Show or hide the rail in every session

Ctrl+B b (prefix_toggle_sidebar), the settings page and appearance.sidebar.enabled show or hide the rail in every session on the daemon, not only in the session you are in. tuios saves the choice to appearance.sidebar.enabled, so a new session starts the same way. Every client of a session shows the rail or hides it together.

To keep the old behaviour, where each session keeps its own shown or hidden rail, set per_session:

[appearance.sidebar]
per_session = true

Two sidebar edges

The existing [appearance.sidebar] settings still configure the original rail. A table for its current edge overrides only the fields it names; the opposite edge stays hidden unless explicitly enabled. Each edge can have its own width, section order and custom command:

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

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

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

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

[appearance.sidebar.right] has the same enabled, width, sections and custom keys. Both edge tables also take the five subagent_* keys. On the original edge, omitted keys retain the legacy settings; on the other edge, an omitted sections uses the default section order. Writing an edge table without enabled = true does not enable that edge. With position = "hidden", explicitly enabled edge tables still draw: if both edges are enabled, the left one supplies the primary rail settings and the right one supplies the opposite rail settings. Unset fields on those explicit edges use the edge defaults; they do not inherit a hidden legacy width, section order or custom command. The file's hidden legacy position is not rewritten. Both rails can show the same built-in sections: they use the same sessions, focused pane's directory listing and repository reading, but have independent section scrolling, keyboard focus and pointer hit areas. A custom command on each edge runs independently: rail/custom belongs to the original rail and rail/secondary/custom to the other. These edge tables are file-only, not set-option targets, because custom commands execute outside panes.

On narrow screens, the optional edge contracts before the original rail; both may hide to leave room for the panes. Resizing either rail by dragging its inner border changes only that edge for this client. In sidebar keyboard focus, e moves focus to the other visible edge (and back); Ctrl+B H independently hides or shows the opposite edge, while Ctrl+B b keeps its existing legacy rail toggle. The opposite-edge toggle does not opt in an edge whose enabled = true was never configured.

Show a daemon session in each rail

To use a rail as a terminal, assign a local daemon session to that edge. Its panes on the session's current workspace stack top to bottom in the rail, independent of the central session's layout and attachment. For example, create two sessions, then edit config.toml:

tuios new side-left --detach
tuios new side-right --detach
[appearance.sidebar]
enabled = true
position = "right"
width = 36

[appearance.sidebar.right]
session = "side-right"

[appearance.sidebar.left]
enabled = true
width = 36
session = "side-left"

Settings → Sidebar exposes separate Left session, Right session, width and workspace controls. Entering a session name enables that edge. An empty session name restores that rail's ordinary sections (including sections and custom). While a daemon session occupies the rail, its ordinary custom-section command does not run. session_workspace = 0 or an omitted value shows the rail on every central workspace; set session_workspace = 2 on one edge to show it only on workspace 2 (or use 1–9). This controls visibility, not the assigned session's own workspace. Each edge is independent, so one can follow while the other is pinned.

Click a pane to type in it. With the rail focused, Ctrl+B then - splits downwards: it creates a normal pane in the assigned daemon session and stacks it below the others. Ctrl+B then c also creates a pane there; Ctrl+B then | stacks it vertically rather than subdividing a narrow rail sideways. Ctrl+B then n or p changes the active pane; clicking any pane's title bar focuses that pane. Each pane uses its normal title and title position, not the assigned session ID. Its close and minimize buttons target that daemon pane; zoom temporarily expands the pane within the rail. The session assignment remains in Settings. There is no extra row above the rail pane's normal border. The rail crops the daemon's existing grid; it does not resize a PTY, suppress leading guest whitespace, or shift cursor and mouse coordinates. A narrow rail does not change the size seen by another viewer. All visible panes remain on screen. If the rail is too short to give every pane at least six rows, it shows a contiguous group containing the active pane; cycling focus brings the others into view.

Switching central workspaces, hiding the rail or detaching this TUI client does not end the assigned daemon session or its processes. Reattaching restores the pane's output. A daemon restart is different: it ends running pane programs and restores saved layouts with new shells. Right-clicking the rail currently opens Sidebar Settings, not a pane picker. The assignment can be entered before its daemon session exists: the rail shows an attach error and retries when the session is created. Standalone mode cannot attach sessions.

The rail's current row

appearance.sidebar.row_style sets how the rail marks the session you are on and the pane that has focus:

ValueWhat it draws
barA bar in the gutter, in the session's colour. This is the default
markerA › in the gutter, in the session's colour. > with ASCII glyphs
underlineThe name underlined, in the session's colour
pillThe name on a fill of the session's colour, with the pill caps of the glyph set
[appearance.sidebar]
row_style = "pill"

A row that waits for a person keeps its attention mark in the gutter. The marker glyph is the marker role of the glyph set (see GLYPHS.md). The option is on the settings page, in the Sidebar section.

The focused pane's row in the terminals section carries the mark. Sometimes the rail does not show that row. The agents row of the pane then carries the mark in its gutter. This occurs in these cases:

  • sections does not include terminals.
  • The rail is narrow and lists an agent pane only in the agents section.
  • The terminals section has no room for the row.
  • The terminals section shows the panes of another session.

The agents row uses the bar or the marker. With underline or pill, it uses the bar.

Pick a path from the files

The path picker types a path at the cursor of a pane. It lists the same folder as the files section: the folder that the shell in the pane is in. Press Alt+; in terminal mode, or Ctrl+B .. Type to filter, Tab to open a folder, and Enter to type the path. See KEYBINDINGS.md.

Where worktrees go

tuios worktree new, New worktree... on the rail and tuios fan make a git worktree for each new session. By default it goes in $XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>, outside the repository. [worktree] path puts it somewhere else, given as a path template:

[worktree]
path = "{{ repo_path }}/.worktrees/{{ branch | slug }}"
VariableWhat it holds
repo_pathThe main checkout's directory
repoIts base name
branchThe branch, as given

| slug turns a value into one folder name: feat/retry becomes feat-retry. Use it on branch. Without it, {{ branch }} keeps the slash and makes a folder per part, so the worktree of feat/x lands inside the worktree of feat, and tuios worktree rm --force on feat deletes both. A relative path starts at repo_path, so .worktrees/{{ branch | slug }} is the same as the example above. A leading ~/ is your home folder. The template has to use branch, or every branch would get the same folder.

The variables are the ones worktrunk's worktree-path uses, and | sanitize is another name for | slug, so a template copied from a worktrunk config works as it is. worktrunk's sanitize turns only / and \ into -, while slug turns every run of characters other than letters, digits, . and _ into one -. A branch with other characters, such as fix--retry or feat+x, can get a different folder name from each tool.

When the worktree is inside the repository and git does not ignore it, the main checkout lists it as untracked, and git add -A there would take it in. tuios then warns after it makes the worktree and names the folder that holds the worktrees, such as /.claude/worktrees/ for .claude/worktrees/{{ branch | slug }}, to add to .gitignore or .git/info/exclude. It never edits those files itself.

The daemon makes every worktree, so it reads the setting, when it starts and when the file changes. The path is then the same whichever client asked. Empty is the default. While it is empty, TUIOS_WORKTREE_DIR in the daemon's environment still moves the default folder (see CLI_REFERENCE.md).

Setup before the agent

[worktree] setup is a shell command that runs in every new worktree before its agent or shell starts. Use it to install dependencies:

[worktree]
setup = "pnpm i"
setup_async = false

These options are in the option reference: worktree.setup, worktree.setup_async.

The new session shows a card at the top right with three stages: the checkout, the setup with its last four lines, and the agent. The rail row shows setup while it runs and setup failed after a failure. A key hides the card of a finished setup.

Without setup_async, the agent starts when the setup passes. When the setup fails, tuios removes the new worktree and the branch it made. It keeps a worktree with an uncommitted change or a nested repository, and a branch with a commit or a branch that was there before. The note on the card says what it kept. The agent does not start. The session stays, and the setup window stays open on its output until you press Enter.

With setup_async = true, a failed setup keeps the worktree and the branch, because the agent may already have work in them.

tuios worktree new --setup and tuios fan --setup set the command for one call, and --setup-async the mode. --setup '' runs no setup.

The daemon reads both keys when it starts. A change in the file applies at once when it clears the command or keeps it. A new command waits for tuios config apply in a terminal outside tuios, or a daemon restart. A process in a pane can write the file, and the daemon runs the command.

Where a review opens

The review overlay (ctrl+b v) opens with the keys on the diff. tab moves them to the file list. [review] focus picks the side a review opens on:

[review]
# Which side has the keys when a review opens: "diff" or "files" (default: "diff")
focus = "files"

It applies to every review that opens, and to an attempt opened from the compare view. A review with no changes opens on the diff, which says so. r, u and b read the open review again and keep the side that has the keys. The setting is on the settings page, in the Behavior section, and tuios set-config review.focus files applies from the next review. A value other than diff or files reads as diff, with a warning when the config loads, and tuios set-config refuses it. See KEYBINDINGS.md.

A review shows the changes since the base when it opens. In a plain repository, the base is the merge base with the upstream branch. Commits you did not push yet are then part of the review. [review] scope picks what a review shows when it opens:

[review]
# What a review shows when it opens: "base" or "uncommitted" (default: "base")
scope = "uncommitted"

u still switches between the two, and b still sets another base. A diff of two attempts in the compare view does not use the setting. The setting is on the settings page, in the Behavior section, and tuios set-config review.scope uncommitted applies from the next review. A value other than base or uncommitted reads as base, with a warning when the config loads, and tuios set-config refuses it.

Repositories in the sessions tree

The sessions section gathers the sessions of a repository into one group. The main checkout's row is the repository's row, and the worktree rows hang off it. The main checkout is the session whose directory is the repository itself, usually on main or master.

tuios main          2 ▾
├─ feat/compact-rail  2
└─ fix/pill-bars      1
  • An unnamed session on that row shows the repository's name. A session with a name you chose keeps that name.
  • A repository with no main checkout session has a row of its own.
  • A repository with only a main checkout session shows a plain row.
  • Only worktree rows hang off the repository's row. With several sessions in the main checkout, the first in the rail's order is the repository's row, and the others are plain rows in their own places. Folding the group does not hide them, and the group's +N does not count them. Several sessions in the main checkout and no worktree session show plain rows and no group.

Each group's row ends in a fold mark. These controls fold and open the group:

  • Click the fold mark.
  • Move the rail cursor to the fold mark and press enter.
  • Right-click the row and select Fold group or Unfold group.
  • Click a repository's own row.

A click on a main checkout's row opens its session. A folded row shows +N for the sessions that it holds, the loudest agent state of the group, and the mark of the attached session when that session is in the group.

Drag a group's row to move the whole group. Drag a worktree row to move it inside its group. The reorder keys follow the same rule.

appearance.sidebar.group_main gives each repository a row of its own, with the main checkout under that row. The option is false by default. An explicit false gives the same layout as no option. The option is on the settings page, in the Sidebar section, as Separate repository row.

[appearance.sidebar]
group_main = true

Independent of the option, the daemon records the main checkout the way it records a worktree, so tuios worktree ls and the worktree verbs see it with the worktrees of the repository.

Keep the files section shut by default

Leave files out of appearance.sidebar.sections to keep the section shut when you attach:

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

Click files in the rail's footer to open the section. Click it again to close it. File search and a click on a folder link also open it.

The section goes after terminals with a share of 25, as in the default layout. A layout with no terminals has it after sessions, and a layout with neither has it above agents. The section stays open for this client until you close it or the client exits. The value of appearance.sidebar.sections does not change.

The files section style

appearance.sidebar.files_style sets how the rail's files section shows a folder:

ValueWhat it shows
listOne folder. .. goes up, and a folder row goes into the folder. This is the default
treeOne tree from the folder. A folder opens under its own row, with indent guides and an open or closed mark
[appearance.sidebar]
files_style = "tree"

In the tree, the rail has these keys on a name:

KeyWhat it does
l, rightOpen the folder. On an open folder, go to its first name
h, leftClose the open folder. On another name, go to its folder
enter, a clickOpen or close the folder. On a file, do what the list does

The file action keys (a, r, d, y, x, p, Y, S) act on the name under the cursor. A new file or a paste goes into the folder of that name. On an open folder, it goes into that folder. With folder_click = "cd", a folder row types a cd into the pane and does not open. With both, a folder row only opens, because a cd moves the root of the tree to that folder.

In both styles, g and G on a file go to the first or last name of the list. Press the key again to go to the first or last row of the rail.

tuios reads a folder only when you open it. It remembers the open folders of each session until tuios stops. You can open 64 folders at most. Each open folder shows its first 2000 names. tuios watches each open folder on this computer and shows a change without a key. A folder that is open under a folder on another computer shows a change when you open it again. When tuios sees that an open folder is gone, it closes the folder. A new folder with the same name starts closed.

The rail's cursor row

When the rail has the keyboard, the row under the cursor has a lighter background, and its text is bold and underlined in the accent colour. appearance.sidebar.cursor_background sets the background of that row.

[appearance.sidebar]
cursor_background = "#3b4261"   # or a slot name, such as "blue", or a role, such as "accent"

The value is a colour. Empty, the default, keeps the theme's background for the cursor row. The colour does not change the text colour, so choose a colour that your text is readable on. The option sets only the row under the cursor while the rail has the keyboard. The rows under the mouse pointer and the cursor of an unfocused rail keep their own background. At 16 colours, the option has no effect: the cursor row is in reverse video. The option is on the settings page, in the Sidebar section.

The rail's section headers

appearance.sidebar.header_style sets how a section header is drawn:

ValueWhat it draws
autoThe label, with a rule after it when header_case is uppercase. This is the default
plainThe label with no rule
ruleThe label and a rule to the rail's edge
pillThe label on a quiet fill, with the pill caps of the glyph set
iconThe section's icon, then the label
[appearance.sidebar]
header_style = "icon"

The icons are glyph roles: section_sessions, section_terminals, section_agents, section_files and section_git (see GLYPHS.md). With Nerd Fonts on, the default icons are Nerd Font icons. The unicode glyph set has its own. With no icon, the header is plain. header_case still sets the case of the label. On a narrow rail, a pill or an icon can leave no room for a header's +.

The rail's section spacing

appearance.sidebar.density sets the space between the rail's sections. normal (the default) stacks them as the rail always has. roomy puts a blank row in front of each section header after the first. The block pinned to the bottom keeps its own line, which holds the divider.

[appearance.sidebar]
density = "roomy"

The panes do not move. Only the rail's rows change.

The rail's cursor row

When the rail has the keyboard, the cursor row has a lighter background. The text of the row is also bold and underlined in the accent colour. This mark does not need the background, so you can see the cursor on a see-through terminal or with background = "off". The gutter keeps its own marks. At 16 colours the cursor row is in reverse video.

A rail section that overflows

A section with more rows than the lines it is given shows as many as fit. It ends in … +N for the rest. The wheel over a section scrolls it. The keyboard cursor scrolls it to keep itself in view.

While rows are out of view, the section draws a scroll thumb in the rail's edge rule, beside its rows and not its heading. The thumb takes the rule's own cell, so the rows keep their full width. Its size is the share of the rows on screen. It reaches the first line only at the top of the section, and the last line only at the bottom, where there is no +N row. A section that fits draws the plain rule.

A hover peek of another session's panes shows the peeked list from its top, ending in +N when the list is longer than the section. When the terminals section is above the sessions section, the peek keeps the section's resting height, so the session row under the pointer does not move. When it is below, as in the default order, the section is sized for the peeked list like any other. The peek gets a thumb on the same terms, at the top of the column, and leaves the attached session's scroll where it was. There is no thumb on the collapsed strip or on a section of one line.

The glyph is the active glyph set's scrollbar_thumb role. It is ┃ by default, # under --ascii-only, and █ in the heavy set. Where the thumb would be the same glyph as the rule, as with a heavy border style, it is drawn as █ (# under --ascii-only). appearance.scrollbar.* and appearance.hide_scrollbar style the pane scroll bar only, not the rail's thumb.

The rail's custom section

The rail has one section whose rows are the output of a command you write. Place custom in appearance.sidebar.sections like any built-in section and describe it in [appearance.sidebar.custom]:

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

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

These options are in the option reference: appearance.sidebar.custom.title, appearance.sidebar.custom.command, appearance.sidebar.custom.refresh.

The command is a dock component that draws on the rail, so the dock's rules apply: it runs in the client, under a three second timeout, with bounded output; SGR colour survives and every other control sequence is stripped; a command that fails, times out or prints nothing leaves the title over an empty section, never an earlier run's rows; five failures in a row stop it until the config reloads or tuios refresh-dock rail/custom; and tuios list-dock-components lists it as rail/custom with why it drew nothing. Rows are cut to the rail's width and to the lines the section's share gives it, with … +N for the ones below the fold. While some are below the fold the section draws a scroll thumb in the rail's edge rule (see A rail section that overflows).

Each run gets the client's environment plus TUIOS_SESSION, TUIOS_SOCKET, TUIOS_RAIL_SECTION (custom), TUIOS_RAIL_WIDTH (the columns a row may use), TUIOS_RAIL_HEIGHT (the most rows the section's share can give it; the rail may give fewer when other sections need the lines), TUIOS_ACTIVE_PANE_ID and TUIOS_ACTIVE_PANE_CWD (the focused pane and its folder, named as [[keybindings.command]] names them). They are read for each run, and an event that lands while a run is going costs one more run after it, so a quick focus change never leaves the old pane's rows on screen. agent-state fires on every change of a pane's agent state, whichever states [notifications.agent] alerts on. The command does not run while the rail is hidden or folded, so the width it is told is never 0, and it runs again when the rail opens.

appearance.sidebar.sections is a settable option, so tuios set-config can place the section. [appearance.sidebar.custom] is read from the file only: the command runs outside every pane on every refresh, as dock commands and hooks do, and in the default open mode any pane can call set-option, so the command stays out of its reach, as daemon.respond_from_shell does.

The rail's pane section

The rail can show a live terminal pane under its own heading. Place pane in appearance.sidebar.sections and describe it in [appearance.sidebar.pane]:

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

[appearance.sidebar.pane]
title   = "tv"
command = "tuiostv-helper view"
height  = 12

These options are in the option reference: appearance.sidebar.pane.title, appearance.sidebar.pane.command, appearance.sidebar.pane.height.

The program runs in a real terminal in the session, so it survives a detach. The pane is not one of your panes: tiling, layouts, the terminals section and tuios list-windows leave it out. tuios list-windows --rail lists it.

The pane is as wide as the rail's content and as tall as the lines the section gets. When the rail changes size, the program gets the new size. When the rail is hidden, folded, narrower than 10 columns or gives the section no lines, the program keeps running at its last size and the client draws nothing for it. An idle program costs no frames. The pane shows text only: kitty images are not drawn in the rail.

Click the pane, or press P in window mode (focus_rail_pane), to type into it. A program that asks for the mouse gets clicks, motion and the wheel. alt+esc, a click outside the pane, or the leader key gives the keyboard back. esc goes to the program.

When the program exits, the pane closes and the section says so. Click the line to start it again. A session has one rail pane, and only the main rail draws it. If two clients name different commands, the last one to ask replaces the pane. [appearance.sidebar.pane] is read from the file only, for the reason [appearance.sidebar.custom] is.

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