Session Rail

The session rail is a sidebar down one edge of the screen. It lists your sessions, the panes in the current session, the files in the focused pane's directory, the agents at work, and the git state of the focused pane. Everything on it can be reached with the mouse or the keyboard.

Try it live: the Workspaces track opens the rail and walks it in your browser.

Showing and hiding it

The rail is on by default, on the right edge, 24 columns wide.

tuios set-config appearance.sidebar.enabled false
tuios set-config appearance.sidebar.position left

In a daemon session, the rail belongs to the session. When you show or hide it on one client, every client of the session shows or hides it, and the panes take the new space on every client. A new session takes the setting of the first client that attaches. When you toggle the rail, TUIOS also keeps the new value in your config for the next new session. A reload of the config file does not change the rail of a running session. The width of the rail stays per client. See The rail with more than one client.

position is right (default), left or hidden. width is the preferred width in columns on a wide screen (default 24). A config file that sets enabled, position or width keeps its value, so an install from before v0.8.0 whose file names them keeps the old rail. On a narrow screen, or after <, the rail collapses to a one-column strip of marks. Hover the strip for a label (tooltips).

The sections

appearance.sidebar.sections is one string that says which sections the rail draws, in what order, and the most each may take:

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

A name left out is a section the rail does not draw. The percent is a ceiling, not a reservation. spacer is an empty block you can repeat to add a gap or push the next section to the bottom. The git and custom sections are not in the default layout, so add them by name:

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

The settings page (, in window mode) has an editor for this under Sidebar, Sections. The full syntax is on the configuration page.

The last section in the layout is pinned to the bottom of the rail. A divider row sits above it. Drag the divider, or put the cursor on it and press < or >, to move the split. A double click on it, or Enter, restores the layout's own share.

appearance.git_dirty (default true) adds counts of staged, changed and untracked paths to the git section. It is the only part of the section that walks the working tree, so turn it off on a very large repository.

Using it with the keyboard

Move the keyboard into the rail with s in window management mode, or Ctrl+B e from anywhere. The same keys take you back to the panes. Esc also leaves.

While the rail has the keyboard, these keys from [keybindings.sidebar] apply:

On a row of the files section, [keybindings.sidebar_files] answers first: a create, r rename, d delete to the trash, D delete permanently, y copy, x cut, p paste, Y copy the absolute path.

On an agent row, [keybindings.sidebar_agents] answers first:

Every key can be rebound. See Configuration.

Edit and search files

Shift+Enter, or Edit in a file's context menu, opens the row in a new pane. The pane runs the editor from Settings, Sidebar, File editor, or $EDITOR when that setting is empty.

Ctrl+B f searches file names below the focused pane's directory. Ctrl+F does the same below the folder the rail shows, while the rail has focus. Type a name or a relative path and press Enter. tuios opens the rail, opens the file's folder, and selects the file.

The search stops after about 2.5 seconds and skips .git, node_modules, .venv and target. Its title says partial when it did not search the whole tree.

Using it with the mouse

• Click a session to switch to it, or a pane to focus it.
• Click the + on a section header to make a session or a terminal. The + beside a machine makes a session on that machine.
• Right-click a row for its menu. A folder's menu has Copy path, which copies its absolute path.
• Hover a row whose title is too long and it scrolls (marquee).
• Click a folder in the files section to walk into it (folder_click).

Agent rows

The agents section lists every pane running an agent, in every session. By default it is sorted by what each one needs from you, in four groups: needs you (an approval, a question, or an error), finished and not yet seen, working, and at rest. Inside a group, rows keep the order the panes were opened, so a row moves only when what it wants from you changes.

Each row shows the pane's state glyph and its name. A row says how long it has been in its state once that is five minutes or more, or when the cursor or pointer is on it. The second line says the one thing the row's group is about:

• Working: what the agent is doing now, such as Bash: go test ./..., when its hooks report it.
• Needs you: a word for what it needs (approval, question, risky, plan) and what the pane asks.
• Finished, not yet seen: the first line of what the agent last said.
• At rest: nothing.

ctx 84% appears once the agent's context is 80% full or more, and 1 queued at the right edge while messages wait in its queue.

│ agents      2 need you
│▎▲ review          4m
│    risky · rm -rf bu…
│ ■ docs
│    Updated CHANGELOG…
│ ● api       1 queued
│    ctx 84% · Bash: go…

While a Claude Code agent has subagents at work, the second line says how many, such as 3 subagents, on any row. An agent that hands work to subagents and ends its turn shows done, and the count shows that the work goes on. On a narrow line, the harness name gives way to the count. The count needs the Claude Code integration, version 3 or later.

│ ○ lead
│    claude · 3 subagents

On a rail 30 columns wide or narrower, a pane running an agent is listed once, in the agents section, and the terminals section keeps the panes that run no agent. Rows that have rested longer than agent_rest_fold (an hour by default) fold into one +N at rest line. Enter or a click on it shows them again. A row that needs you, a working agent, the focused pane, a pane with messages queued and a pane whose agent has subagents at work never fold.

[appearance.sidebar.agent_row] picks which tokens a row shows, in what order, and how each is coloured. It is a table, so set it in config.toml rather than with set-config:

[appearance.sidebar.agent_row]
# the shipped list; state, host, prompt and $key are the others
tokens = ["session", "need", "harness", "name", "elapsed", "context", "subagents", "pr", "meta", "now", "message"]

[[appearance.sidebar.agent_row.elapsed.rule]]
gt = 30
fg = "warning"

pr shows the pull request of the session's worktree branch and its checks, such as PR #12 open pass. A tokens list you wrote gets no new tokens, so add subagents or pr to it to see them.

A rule has exactly one test (equals, contains, starts_with, gt or lt) and sets fg, bold or both. For elapsed, gt and lt compare minutes. The first matching rule wins, with at most eight per token.

On a narrow rail

When a row does not fit, the rail shares its columns between the name and the other parts of the row, such as the state, the time or the queue count.

• A part is shown whole or not at all. The rail never cuts a part short.
• The parts at the right end of the row have priority. When one part does not fit, the next part can still use the space.
• The name keeps at least eight characters and an ellipsis. It then takes every column that the other parts leave.
• The harness before a name, and the branch of a session, stay only while the whole name fits beside them. When the harness goes, the session before it goes too. So api/deploy never reads as a harness called api.
• The queue count on an agent row takes the longest form that fits: 2 queued, then 2q.

A machine that does not answer keeps its header row. The right end of the row says why:

• offline, or seen 3m ago for a machine that answered before and then dropped off.
• no daemon, no tuios or version for a machine that answered and refused.
• connecting or reconnecting while TUIOS tries the link.

When messages wait for the machine, the count comes first, as in 3 queued, offline. On a narrow rail, the row shows 3 queued, and then the count in place of part of the name. With no messages waiting, a narrow row shows ✕ (x with ASCII glyphs), so a down machine does not look like one that is up. A machine that is connecting gets no mark.

Other options

"cd here" types a cd only into a pane whose shell is at its prompt. In daemon mode, the daemon does this check. TUIOS types no cd for a folder whose name holds a quote, a backslash or a control character. The dock says when it did not type.

All of these live under [appearance.sidebar]. appearance.session_colors gives each session its own colour on the rail, and appearance.session_border carries that colour onto every pane border.

Related