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/paymentsWith 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:
| Term | Keeps |
|---|---|
kind:agent, kind:session, kind:workspace (or kind:ws), kind:pane | Rows of that kind |
space:NAME | Rows of the sessions filed under that space |
ws:N | Agents, 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.
| Key | Does |
|---|---|
| The list keys | Move. See Lists and the settings page |
| Enter | Go there: the session, then the workspace, then the pane |
| Ctrl+R | Rename the session or workspace on the row. Go-to stays open under the rename |
| Ctrl+D | Delete the session on the row, after a y. Never the session you are on |
| Ctrl+U | Clear the query |
| Esc | Close |
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
- Press Ctrl+B Q. Each pane of the workspace shows a large label with its name under it.
- Type a label. TUIOS focuses that pane and the labels close.
| Keys | Does |
|---|---|
| A label, such as 3 | Focus that pane |
| Backspace | Take back the last key of a two-key label |
| Esc, the leader | Close the labels |
| q | Close 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.

| Keys | Does |
|---|---|
| j, k, arrows | Move |
| l, → | Open a session or a workspace |
| h, ← | Close it, or go to its parent row |
| Space | Open or close |
| Enter | Go to the row: the session, the workspace and the pane |
| / | Search |
| v | Change the layout: tree, flat, cards |
| Esc, q | Close 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. Forssh, 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:
| Layout | Shows |
|---|---|
tree | Sessions, their workspaces and their panes |
flat | One row for each pane, with its session and workspace |
cards | Two 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"Search
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 screenEach 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.
Hints
Put a short label on each URL, path, hash, address and number in a pane, then type the label to copy, paste or open the text.
Links
Open a link in a pane with Ctrl+click, choose the click and the opener, and see which terminals pass the click to TUIOS.
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.
