Server, session, window, pane

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

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

A SServer contains sessions. Each SSession contains links to windows, and each SWindow contains panes. Commands run inside a SPane, 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:

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

Read the hierarchy:

// Three tmux commands total, not one per object: walking down would cost a
// command per session and per window.
for branch in server.hierarchy().await? {
    let session = &branch.session;
    println!("{session} {} ({} windows)",
        session.name().to_string_lossy(), session.window_count());

    for built in &branch.windows {
        let window = &built.window;
        println!("  {window} {}", window.name().to_string_lossy());

        for pane in &built.panes {
            println!("    {pane}");
        }
    }
}

Client: a view, not a child¶

A SClient 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 odestroy-unattached. Closing the last attached client can therefore destroy a session configured with that option.