# Session Rail URL: https://tuios.dev/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. **Try it live:** the [Workspaces track](https://tuios.dev/learn?t=workspaces) 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. | How | What it does | | ---------------------------- | ---------------------------------------------- | | Ctrl+B b | Show or hide the rail | | Palette: `Toggle sidebar` | The same | | `appearance.sidebar.enabled` | Whether a new session shows it. Default `true` | ```bash 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](https://tuios.dev/docs/sessions#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 | Section | What it lists | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessions` | Every session, grouped by machine when you have [remote hosts](https://tuios.dev/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. The list updates when a file is added, removed or renamed. See [the files section](https://tuios.dev/docs/configuration#the-files-section) | | `agents` | Every pane running a coding agent, with its state. See [Agents](https://tuios.dev/docs/agents) | | `git` | The focused pane's repository, branch, and how far it is ahead of or behind its upstream | | `custom` | The output of a command you write, one row per line. See [The custom section](https://tuios.dev/docs/configuration#the-custom-section) | `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` and `custom` sections are not in the default layout, so add them 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.dev/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 what needs you (`you`, the default), by priority (`pri`), or by most recent (`rec`) | | 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, Y copy the absolute path. On an agent row, `[keybindings.sidebar_agents]` answers first: | Key | Action | | --- | ------------------------------------------------------------------------------------------------------------------------ | | r | Reply to the agent. The line opens under the Inbox, and the message is typed when the agent is at rest | | v | [Review](https://tuios.dev/docs/agent-inbox#reviewing-an-agents-changes) the pane's changes | | u | Mark the pane's finished turn unread again, for every client | | z | Snooze the pane's Inbox item | | x | Drop the newest queued message. u within 10 seconds queues it again. With nothing queued, x opens the menu as on any row | Every key can be rebound. See [Configuration](https://tuios.dev/docs/configuration#keybindings). ## 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](https://tuios.dev/docs/agent-inbox#replying-and-the-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](https://tuios.dev/docs/agents#the-agent-reports-for-itself), 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`: ```toml [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 | Key | Default | Meaning | | ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | `show_glyphs` | `true` | Agent state glyph on each row | | `show_counts` | `true` | Pane count on each session row | | `show_numbers` | `false` | Show the switch number before each local session name. The number is the one `switch_session_N` opens, for sessions 1 to 9 | | `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`. TUIOS types a `cd` only into a shell at its prompt | | `file_actions` | `true` | Allow create, rename, delete, copy, cut and paste | | `file_delete` | `"trash"` | `trash` or `permanent` | | `agent_rest_fold` | `"1h"` | How long an agent row rests before it folds. A duration, or `off` | | `background` | `""` | The rail's background: `off`, `theme` or `#RRGGBB`. Empty follows `appearance.background` | "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. > **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.dev/docs/session-rail)*