About¶

See also

API Reference

libtmux is a typed abstraction layer for tmux.

It builds upon the concept of targets -t, to direct commands against individual sessions, windows and panes and FORMATS, template variables exposed by tmux to describe their properties. Think of -t analogously to scope.

common.TmuxRelationalObject acts as a container to connect the relations of Server, Session, Window and Pane.

Object

Child

Parent

Server

Session

None

Session

Window

Server

Window

Pane

Session

Pane

None

Window

Internally, tmux allows multiple servers to be run on a system. Each one uses a socket. The server-client architecture is executed so cleanly, many users don’t think about it. tmux automatically connects to a default socket name and location for you if none (-L, -S) is specified. A server will be created automatically upon starting if none exists.

A server can have multiple sessions. Ctrl+a s can be used to switch between sessions running on the server.

Sessions, windows and panes all have their own unique identifier for internal purposes. common.TmuxMappingObject will make use of the unique identifiers (session_id, window_id, pane_id) to look up the data stored in the Server object.

Object

Prefix

Example

Server

N/A

N/A, uses socket-name and socket-path

Session

$

$13

Window

@

@3243

Pane

%

%5433

Similarities to tmux and Pythonics¶

libtmux was built in the spirit of understanding how tmux operates and how python objects and tools can abstract the APIs in a pleasant way.

libtmux uses FORMATTERS in tmux to give identity attributes to Session, Window and Pane objects. See format.c.

How is libtmux able to keep references to panes, windows and sessions?

Tmux has unique IDs for sessions, windows and panes.

panes use %, such as %1234

windows use @, such as @2345

sessions use $, such as $13

How is libtmux able to handle windows with no names?

Tmux provides window_id as a unique identifier.

What is a {pane,window}_index vs a {pane,window,session}_id?

Pane index refers to the order of a pane on the screen.

Window index refers to the number of the window in the session.

To assert pane, window and session data, libtmux will use Server.sessions(), Session.windows(), Window.panes() to update objects.

Naming conventions¶

Because this is a python abstraction and commands like new-window have dashes (-) replaced with underscores (_).

Reference¶