# Session Rail

URL: https://tuios.gaurav.zip/docs/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 |

```bash
tuios set-config appearance.sidebar.enabled true
tuios set-config appearance.sidebar.position right
```

`position` 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](https://tuios.gaurav.zip/docs/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](https://tuios.gaurav.zip/docs/configuration#the-files-section)                                                                                                                      |
| `agents`    | Every pane running a coding agent, with its state. See [Agents](https://tuios.gaurav.zip/docs/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:

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

```toml
[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](https://tuios.gaurav.zip/docs/configuration#sections).

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](https://tuios.gaurav.zip/docs/configuration#keybindings).

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

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

## Related

*[An interactive figure goes here. Open the page to use it.](https://tuios.gaurav.zip/docs/session-rail)*