libtmux Documentation

libtmux follows the hierarchical structure of a tmux server. You can navigate through related objects in both directions (down to children or up to parents):

1. Server: The top-level object containing all sessions.
2. Session: Groups one or more windows.
3. Window: Groups one or more panes.
4. Pane: The leaf node (the actual terminal area).

Traversal Examples:

• Downwards: Use properties like session.windows to list children.
• Upwards: Use properties like pane.session to jump from a pane back to its parent session.

Note: Accessing these properties queries tmux fresh every time. For performance in loops, bind the collection to a variable first.

>>> # Downward traversal
>>> session.windows
[Window(...), ...]

>>> # Upward traversal
>>> pane.session
Session($... ...)

>>> # Full upward path
>>> pane.window.session.server is server
True

When working with libtmux, be aware of the following operational constraints:

• tmux availability: A tmux server must be running and accessible via the default socket or a specifically provided socket.
• Session requirement: Certain operations require the tmux server to have at least one active session.
• Format string dependency: The availability of specific format strings used by libtmux is strictly dependent on the version of tmux currently running.

libtmux objects are linked. You can navigate from a child object up to its parent (e.g., from a Pane to its Window, or from a Window to its Session).

pane.window
pane.window.session

In libtmux, a Client represents an attached terminal (the view a user sees). A single tmux server can host multiple clients simultaneously (e.g., from multiple tmux attach commands).

Unlike the standard hierarchy (Server → Session → Window → Pane), a Client is not an owner; it points at a Session, Window, or Pane that it is currently viewing.

Key distinction: Identity vs. View

• Identity: The client_name (the tty path) is the stable identity of the client for the lifetime of the attachment.
• View: Fields like session_id, window_id, pane_id, and client_session are snapshots of what the client was viewing at the moment they were read. These become stale immediately if the user performs actions like switch-client, select-window, or `select-pane.

When you use Pane.send_keys(), the command runs in the background and control returns to your Python script immediately. To manage these processes, you must use the Pane object as your handle. Since send_keys() is non-blocking, you cannot rely on the function return value to know if a process is finished; instead, you must poll the pane's output using Pane.capture_pane() and look for specific text markers (e.g., echo "DONE") to determine the process state.

import time

# Start a background process
proc_pane.send_keys('sleep 2 && echo "Process complete"')

# The script continues immediately while the command runs in the pane
time.sleep(0.1)
# Use capture_pane() to check status later

A workspace is a single window divided into multiple panes, each running a different program. You can build these layouts from Python using four primary methods:

1. libtmux.Session.new_window: To open a new window.
2. libtmux.Window.split: To divide a window into panes.
3. libtmux.Window.select_layout: To arrange panes using built-in tmux layouts.
4. libtmux.Pane.send_keys: To send commands to a specific pane.

To follow along with examples, you need one terminal running a live tmux server (tmux) and another running a Python prompt to drive it.

# Terminal 1: Start tmux
$ tmux

# Terminal 2: Start Python
$ python

To ensure your code remains stable across updates, you must distinguish between the public API and internal implementation details.

• Public API: Any name you can import from the libtmux namespace without a leading underscore in its module path (e.g., libtmux.Session). These are covered by a deprecation policy and are safe to use.
• Internal API: Any name containing a leading underscore in its module path (e.g., libtmux._internal.* or libtmux._vendor.*). These are implementation details that can change or be removed between any release without warning.

Recommendation: Always stick to the public API. If you find yourself needing a feature that is currently only available in an _internal module, file an issue to request its promotion to the public API.

Choose your filtering strategy based on data volume and complexity:

To ensure stability when tmux state changes (like indexes shifting), libtmux uses unique internal identifiers assigned by tmux. These are stored as attributes on each object, allowing libtmux to reliably track the same entity even after a state refresh.