Finding a pane

Jump to a pane by its label, or find any pane in any session by its name, folder, command or screen text.

Three keys take you somewhere without walking through the panes one by one. Go-to lists every agent, session, workspace and pane in one search. Pane labels number the panes on the screen, as tmux's display-panes does. The pane navigator lists every pane in every session, as tmux's choose-tree does, and searches them.

Go to anything

Ctrl+B G opens go-to. It lists every place you can go in one list: agents, sessions, the workspaces of each session, and panes. The action is goto_picker, and the palette has it as "Go to: an agent, session, workspace or pane". Each row starts with its kind, then says where the place is:

agent      claude · payments › 1 › api    needs you: approve Bash ●
session    payments [space: surge]                          3 panes
workspace  payments › 2 · api-tests                          1 pane
pane       payments › 1 › nvim                ~/src/payments

With nothing typed, the first row is the place you were on last, so Ctrl+B G and Enter take you back. The agents that need you come next, the one waiting longest first, then the other places you were on recently, then every agent, session and workspace. Panes are listed once you type something.

Typed words are a fuzzy search over the names a row shows: the session, the workspace, the pane and its folder, and for an agent its harness and its last message. A key:value term narrows the rows instead, and every term has to match. The terms are the selector the agents view takes (harness:, state:, needs:you, session:, group:, host:, name:), and three more:

TermKeeps
kind:agent, kind:session, kind:workspace (or kind:ws), kind:paneRows of that kind
space:NAMERows of the sessions filed under that space
ws:NAgents, workspaces and panes on that workspace, by number or name

A value is a glob, and commas mean any of them, as in kind:session,workspace. @, # or ! at the start of the query is kind:agent, kind:session or kind:workspace: #space:surge lists the sessions in the surge space, and @needs:you the agents that need you.

KeyDoes
The list keysMove. See Lists and the settings page
EnterGo there: the session, then the workspace, then the pane
Ctrl+RRename the session or workspace on the row. Go-to stays open under the rename
Ctrl+DDelete the session on the row, after a y. Never the session you are on
Ctrl+UClear the query
EscClose

Some keys open go-to with a filter typed: Ctrl+B S on # (the sessions), Ctrl+B W on ! session:NAME (this session's workspaces), and the palette's "All windows" on kind:pane session:NAME (this session's panes). With # NAME typed and no session called NAME, Enter makes that session.

A session on another machine is listed with its agents, and Enter on it attaches that machine as the rail does. Workspaces and panes are listed for the sessions on the machine you are attached to.

Pane labels

  1. Press Ctrl+B Q. Each pane of the workspace shows a large label with its name under it.
  2. Type a label. TUIOS focuses that pane and the labels close.
KeysDoes
A label, such as 3Focus that pane
BackspaceTake back the last key of a two-key label
Esc, the leaderClose the labels
qClose the labels, when q is not a label key

The labels are digits by default, in the order that select_window_1 to select_window_9 count the panes. So label 3 is the pane that 3 selects in window mode. A minimised pane gets no label. With more panes than keys, a label has two keys.

Use other keys, such as the home row, in config.toml:

[panes]
label_keys = "asdfghjkl"

Letters a to z and digits are allowed. The first keys go to the first panes. A key typed with Shift is the same key.

When a pane is zoomed, the zoomed pane shows its label, and a list under it shows the labels of the panes the zoom hides. A label of a hidden pane moves the zoom to that pane. A pane that is mostly off the screen, or too small for its label, is in the same list.

The labels own the keyboard while they are up. In multifocus, a label key or a paste does not reach any pane. The labels close when the layout changes (a pane opens, closes, moves or zooms) and on a click or the mouse wheel.

The action is display_panes. Bind it to another key in [keybindings.prefix_mode].

The pane navigator

Press Ctrl+B /. The navigator has three boxes. Search is at the top and shows how many panes match, such as 3/7. Panes lists the sessions, workspaces and panes. Preview shows the screen of the pane under the cursor, in the colors of that pane. The sessions on your remote hosts are in the tree too.

The pane navigator. The Panes box lists the sessions demo, api and docs. The Preview box shows the screen of the selected pane.
KeysDoes
j, k, arrowsMove
l, →Open a session or a workspace
h, ←Close it, or go to its parent row
SpaceOpen or close
EnterGo to the row: the session, the workspace and the pane
/Search
vChange the layout: tree, flat, cards
Esc, qClose the navigator

A click on a pane goes to it. A click on a session or a workspace opens or closes it.

What a row shows

A session name has the color of the session in the sidebar. Its workspaces and panes hang under it on tree lines. A pane row shows:

  • a dot with the state of the agent in the pane, if there is one;
  • the pane name. A pane that has no name and no title shows its folder;
  • the command that runs in the pane, after a │. At a prompt this is the shell. For ssh, the host follows when the shell reports its commands (OSC 133);
  • the folder.

The current session and the current pane say current. The counts at the right are the panes in each session and workspace. A search shows the matched characters in the accent color.

Layouts

Press v to change how the list shows the panes:

LayoutShows
treeSessions, their workspaces and their panes
flatOne row for each pane, with its session and workspace
cardsTwo rows for each pane: the name and the command, then the session, the workspace and the folder

Your client keeps the last layout until it closes. Set the first layout in config.toml:

[panes]
navigator_layout = "flat"

Press / and type. The search reads each pane's name, title, folder, running command, session and workspace, and the last 40 lines of its screen. So you can find the pane where a build failed, or the server you logged in to, even when you did not name the pane. A pane that matches only by its screen text shows the matching line on its row.

Esc stops the search and keeps the results. A second Esc clears the search. A paste in the search line is search text.

The current session's panes are read from your client, and their preview is live. The other sessions are read when the navigator opens, so their preview shows the screen as it was then. The preview shows colors and text only. Links, clipboard writes and other control sequences from a pane do not reach your terminal. One load reads at most 150 screens and waits at most 8 seconds. A session that does not answer in time says so on its row.

The action is choose_tree.

From a script

list-windows --all prints the same rows as the navigator:

tuios list-windows --all                      # every pane of every session
tuios list-windows --all --all-hosts --json   # and the panes on each host
tuios list-windows --all --text 20 --json     # with the last 20 lines of each screen

Each row has session, workspace, workspace_name, window_id, name, title, command, cwd, focused and agent_state. A pane on another machine also has host and "untrusted": true. --text reads with capture-pane, so the same pane grants apply: a pane that holds only read gets its own session, and the JSON has an errors entry for the rest.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page