Finding a Pane

Finding a pane

Two keys take you to a pane without walking through the panes one by one. 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.

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.

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. 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:

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 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.