Server, session, window, pane

Edit this page on GitHub

libtmux models tmux’s server, session, window, and pane objects:

Server
├── Session
│   └── Window
│       └── Pane
└── Client (attached view)

A Server contains sessions. Each Session contains links to windows, and each Window contains panes. Commands run inside a Pane, where you send input and capture output. A window can be linked to more than one session.

Stable identity, not name or indexLink to section

tmux assigns a unique ID to each session, window, and pane at creation. The ID remains stable for that object’s lifetime even if its name or index changes:

Python handles use the object ID to refresh their fields. Immutable snapshots, such as those in TypeScript, Swift, and Go, use IDs to identify the same tmux object across reads.

Walking the whole tree, in each port:

Client: a view, not a childLink to section

A Client represents a terminal attached to a session. Several clients can view the same server, and each can switch sessions or windows independently. Client fields describe the view at the time of the read.

A control-mode connection is also a client. It appears in list-clients, counts toward session_attached, and affects attachment-dependent behavior such as destroy-unattached. Closing the last attached client can therefore destroy a session configured with that option.

What differs between portsLink to section

Ports differ in how they read state and report failures:

• Refreshing state. Python objects reflect their last read until you call .refresh(). TypeScript, Swift, and Go also provide snapshots whose relationships can be queried without another tmux command.
• Blocking and async calls. Python and Java use blocking calls. Rust, TypeScript, .NET, and Swift provide async APIs. Go uses ordinary calls with contexts for cancellation and deadlines.
• Failure handling. Python and .NET raise exceptions. C++ returns expected<T, CommandFailure>. Some commands have an expected negative answer, such as has-session when a session is absent; check the method’s result contract before treating that answer as a failure.

See Control mode vs one-shot for command costs and connection behavior.