See also

API Reference

libtmux is an abstraction layer for tmux.

It builds upon the concept of targets -t, to direct commands against individual session, windows and panes and FORMATS, template variables exposed by tmux to describe their properties. Think of -t analagously 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 ran 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 API’s 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 ID’s for sessions, windows and panes.

panes use %, such as %1234

windows use @, such as @2345

sessions use $, for money, such as $

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 # of the window in the session.

To assert pane, window and session data, libtmux will use Server.list_sessions(), Session.list_windows(), Window.list_panes() to update objects.

Naming conventions

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