Traversal

Edit this page on GitHub

Use relationships to move between sessions, windows, and panes. Server, session, window, pane explains the hierarchy and snapshot model. This page covers relationship calls, collection membership, and object identity.

Down the hierarchyLink to section

List children through the parent object or a captured snapshot. Whether a read issues another tmux command depends on the API, independently of whether the call is async; see Server, session, window, pane.

TypeScript’s session.windows and window.panes read the graph loaded by await server.sessions() without additional tmux commands. Rust also provides server.attached_sessions() to list only sessions with an attached client.

All panes in a sessionLink to section

Use a session-wide pane collection when the task spans several windows, such as finding a command or capturing output from every pane. A window linked to multiple sessions still refers to the same tmux panes. Check whether the API reads live state or traverses a captured graph before reusing its result.

PythonLink to section

libtmux.Session.panes runs a session-scoped list-panes -s read. Use it to list panes across the session’s windows without manually listing each window.

TypeScriptLink to section

session.Session.panes returns a Selection from the session’s captured graph. Reading it does not issue another tmux command; refresh the snapshot when you need newer state.

RustLink to section

session.Session.panes performs a live listing and returns a Result from the async call. Handle a command failure before using the returned panes.

GoLink to section

tmux.Session.Panes reads captured relations without another tmux command. The relation must have been included in the read that produced the session; an uncaptured relation does not establish that the session has no panes.

.NETLink to section

LibTmux.Session.Panes reads the session’s captured relations. It does not issue a tmux command; an incomplete capture may lack the required relation.

C++Link to section

libtmux::Session::panes runs a session-scoped list-panes command. Inspect the returned result before traversing the panes.

SwiftLink to section

Snapshot.panes(of:) accepts a session or a window. The session overload traverses the captured graph and deduplicates pane IDs without a tmux read.

JavaLink to section

Java has no direct session-wide pane member. Traverse Session.windows() and then Window.panes() in the captured relations. Deduplicate pane IDs when combining results from sessions that may share linked windows.

Up the hierarchyLink to section

Parent lookups may read captured data or query tmux again. Check the method’s read and failure semantics; Server, session, window, pane introduces that distinction:

Go and Rust return optional relationship results. .NET’s .Window, .Session, .ActiveWindow, and .ActivePane read captured state synchronously and throw IncompleteSnapshotException if that capture lacks the required context.

One walk, down and back upLink to section

Start with a session, traverse to a window and pane, then look up the parent and compare its identity with the starting object:

The active childLink to section

“Which window is in front right now” and “which pane would a command actually reach” are common enough questions that most ports expose the active child directly rather than making you filter a list:

In Swift, filter snapshot children by isActive. Other ports expose an active-child method or property on the parent. Format-token fields describes the underlying window_active and pane_active fields.

Is it in that collection?Link to section

Checking membership generally goes through whatever your language uses for collection membership, since most of these calls already return an ordinary array, slice, or list:

• Python overloads in directly on its QueryList: window in session.windows, pane in window.panes.
• Java, C++, and .NET return standard collections. Use their standard membership operations with the identity comparison appropriate to the port.
• TypeScript returns iterable Selection<T> objects. Iterate over the selection and compare IDs, or spread it into an array for standard array operations.
• Go and Rust return slices or vectors. Iterate and compare object IDs when testing membership by tmux identity.

Is this the same object?Link to section

Compare IDs to determine whether two handles refer to the same tmux object on the same server. Equality operators vary by port:

Swift’s equality compares captured state. Compiler-synthesized equality for Session, Window, and Pane compares every stored property, including dimensions and current command. Two reads can compare unequal even when they describe the same tmux object. Compare .id when checking identity on the same server.