# The dock and the session rail

URL: https://tuios.dev/docs/configuration/dock-and-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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/CONFIGURATION.md). The [Configuration](https://tuios.dev/docs/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`](https://tuios.dev/docs/option-reference#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:

```toml
[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`](https://tuios.dev/docs/option-reference#dock.clock.format) or
[`appearance.clock_format`](https://tuios.dev/docs/option-reference#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](https://tuios.dev/docs/configuration/motion-rendering-and-themes#colour-values).
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:

```toml
[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](https://tuios.dev/docs/configuration/motion-rendering-and-themes#colour-values). 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:

```toml
[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:

```toml
[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:

```toml
[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](https://tuios.dev/docs/configuration/motion-rendering-and-themes#colour-values).
- `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`](https://tuios.dev/docs/option-reference#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`](https://tuios.dev/docs/option-reference#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`:

```toml
[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:

```toml
[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`:

```sh
tuios new side-left --detach
tuios new side-right --detach
```

```toml
[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`](https://tuios.dev/docs/option-reference#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 |

```toml
[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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/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](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#pick-a-path).

## 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:

```toml
[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](https://tuios.dev/docs/cli-reference#tuios_worktree_dir)).

## 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:

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

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`worktree.setup`](https://tuios.dev/docs/option-reference#worktree.setup), [`worktree.setup_async`](https://tuios.dev/docs/option-reference#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:

```toml
[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](https://tuios.dev/docs/keybindings/agents-view#the-review-overlay).

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:

```toml
[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`](https://tuios.dev/docs/option-reference#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`.

```toml
[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`](https://tuios.dev/docs/option-reference#appearance.sidebar.sections) to keep the section shut when
you attach:

```toml
[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`](https://tuios.dev/docs/option-reference#appearance.sidebar.sections) does not change.

## The files section style

[`appearance.sidebar.files_style`](https://tuios.dev/docs/option-reference#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 |

```toml
[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`](https://tuios.dev/docs/option-reference#appearance.sidebar.cursor_background) sets the background of that row.

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

The value is a [colour](https://tuios.dev/docs/configuration/motion-rendering-and-themes#colour-values). 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`](https://tuios.dev/docs/option-reference#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                                                     |

```toml
[appearance.sidebar]
header_style = "icon"
```

The icons are glyph roles: `section_sessions`, `section_terminals`,
`section_agents`, `section_files` and `section_git` (see
[GLYPHS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/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`](https://tuios.dev/docs/option-reference#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.

```toml
[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`](https://tuios.dev/docs/option-reference#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`](https://tuios.dev/docs/option-reference#appearance.sidebar.sections) like any built-in section and
describe it in `[appearance.sidebar.custom]`:

```toml
[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](https://tuios.dev/docs/option-reference): [`appearance.sidebar.custom.title`](https://tuios.dev/docs/option-reference#appearance.sidebar.custom.title), [`appearance.sidebar.custom.command`](https://tuios.dev/docs/option-reference#appearance.sidebar.custom.command), [`appearance.sidebar.custom.refresh`](https://tuios.dev/docs/option-reference#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](https://tuios.dev/docs/configuration/dock-and-rail#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`](https://tuios.dev/docs/option-reference#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`](https://tuios.dev/docs/option-reference#appearance.sidebar.sections) and describe it in `[appearance.sidebar.pane]`:

```toml
[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](https://tuios.dev/docs/option-reference): [`appearance.sidebar.pane.title`](https://tuios.dev/docs/option-reference#appearance.sidebar.pane.title), [`appearance.sidebar.pane.command`](https://tuios.dev/docs/option-reference#appearance.sidebar.pane.command), [`appearance.sidebar.pane.height`](https://tuios.dev/docs/option-reference#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.
