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 tabColours 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 = falseBesides {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 printedattention_fgis 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_markerandactivity_markergo 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 = trueTwo 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:
| Value | What it draws |
|---|---|
bar | A bar in the gutter, in the session's colour. This is the default |
marker | A › in the gutter, in the session's colour. > with ASCII glyphs |
underline | The name underlined, in the session's colour |
pill | The 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:
sectionsdoes not includeterminals.- 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 }}"| Variable | What it holds |
|---|---|
repo_path | The main checkout's directory |
repo | Its base name |
branch | The 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 = falseThese 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
+Ndoes 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 grouporUnfold 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 = trueIndependent 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:
| Value | What it shows |
|---|---|
list | One folder. .. goes up, and a folder row goes into the folder. This is the default |
tree | One 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:
| Key | What it does |
|---|---|
l, right | Open the folder. On an open folder, go to its first name |
h, left | Close the open folder. On another name, go to its folder |
enter, a click | Open 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:
| Value | What it draws |
|---|---|
auto | The label, with a rule after it when header_case is uppercase. This is the default |
plain | The label with no rule |
rule | The label and a rule to the rail's edge |
pill | The label on a quiet fill, with the pill caps of the glyph set |
icon | The 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 = 12These 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.
Display, mouse and shell
Display, mouse and shell: part of the Configuration of TUIOS.
Agents
Agents: part of the Configuration of TUIOS.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.