tmuxtmuxConcepts

Choose documentation 1

latest

tmux manual version

Latest (3.7c) 3.7c 3.2a
English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

Edit this page on GitHub

Server, session, window, pane

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 index

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:

ObjectID prefixExample
Session$$13
Window@@3243
Pane%%5433
Server-identified by socket name or path instead

Use stable IDs to identify the same tmux object across reads. Names and indexes can change while a program is running.

Read the hierarchy:

for session in server.sessions:
print(session.session_name)
for window in session.windows:
print(" ", window.window_index, window.window_name)
for pane in window.panes:
print(" ", pane.pane_id, pane.pane_current_command)

Client: a view, not a child

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 ports

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, C#, and Swift provide async APIs. Go uses ordinary calls with contexts for cancellation and deadlines.
  • Failure handling. Python and C# 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.

Snapshots and live commands

Server.Snapshot(ctx) reads the hierarchy. The resulting relationship methods read that captured data without another tmux command. A boolean return value reports whether a relationship was captured. Use Session.SearchWindows or Server.SearchPanes for current live state, and check the returned error.

Calls that contact tmux accept a context for cancellation and deadlines. Cancelling a mutation does not prove that tmux never received it; check the resulting state before retrying. Errors and exceptions covers failure handling.

tmux command reference

Read the tmux command references for list-sessions, list-windows, and list-panes. The target syntax explains IDs, names, and indexes.

Esc

Type to search.