Session Rail
The sidebar that lists sessions, machines, panes, files, agents and git state.
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.
Turning it on
The rail is off by default.
| How | What it does |
|---|---|
| Ctrl+B b | Show or hide the rail |
Palette: Toggle sidebar | The same |
appearance.sidebar.enabled = true | Show it on every start |
tuios set-config appearance.sidebar.enabled true
tuios set-config appearance.sidebar.position rightposition is left (default), right or hidden. width is the preferred width in columns on a wide screen (default 28). 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
| Section | What it lists |
|---|---|
sessions | Every session, grouped by machine when you have remote hosts. Worktree sessions sit under their repository, labelled by branch. A global group appears once a second machine is reachable |
terminals | The panes of the current session |
files | The focused pane's directory. See the files section |
agents | Every pane running a coding agent, with its state. See Agents |
git | The focused pane's repository, branch, and how far it is ahead of or behind its upstream |
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 section is not in the default layout, so add it 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:
| Key | Action |
|---|---|
| j / k, Down / Up | Move the cursor |
| g / G, Home / End | First or last row |
| l / h, Right / Left | Next or previous section |
| Tab / Shift+Tab | Cycle sections |
| Enter | Activate the row: attach the session, or focus the pane |
| 1-9 | Jump to a session by its position |
| J / K | Move a session or machine down or up the rail |
| n | New session. Asks which machine when there is more than one |
| t | New terminal in the session |
| r | Rename the pane under the cursor |
| c | Recolour the pane under the cursor |
| m | Open the menu for the row under the cursor |
| x | Open that menu on its Close or Kill entry |
| f | Agents: show all sessions, or only this one |
| o | Agents: sort by priority, or by most recent |
| i | Open the mailbox for the pane under the cursor |
| / | Search every pane in every session. @state filters by agent state |
| < / > | Collapse or expand the rail. On the divider, move the split |
| ? | Show the rail's keys |
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.
Every key can be rebound. See Configuration.
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.
- 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
Each row in the agents section shows the pane's agent state glyph, its name, and how long it has been in that state. When the rail has room, a second line carries the agent's harness and the note it reported.
[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]
# harness, name, state, elapsed, message, session, host
tokens = ["session", "harness", "name", "elapsed", "message"]
[[appearance.sidebar.agent_row.elapsed.rule]]
gt = 30
fg = "warning"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.
Other options
| Key | Default | Meaning |
|---|---|---|
show_glyphs | true | Agent state glyph on each row |
show_counts | true | Pane count on each session row |
marquee | true | Scroll a hovered row's long title |
tooltips | true | Label the collapsed strip on hover |
file_icons | true | A Nerd Font icon per file type |
file_icon_colors | true | Draw each file icon in its type's colour |
folder_click | "navigate" | navigate, cd (send the focused pane there) or both |
file_actions | true | Allow create, rename, delete, copy, cut and paste |
file_delete | "trash" | trash or permanent |
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.
Older config keys
The flat sidebar_* keys and the show_windows and show_agents booleans still load. They are folded into [appearance.sidebar] and sections when the file is read. Use the new keys in new configs.