tmuxp is usable but still needs your help reporting errors, bugs and usability feedback. If you encounter an error, please post on the Issue tracker.


See also

API Reference

tmuxp is an abstraction layer against tmux’ command line arguments.

util.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. Most users worry since tmux will communicate to a default server automatically. If one doesn’t exist, tmux does it for you.

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. util.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

tmuxp is 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.

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

How is tmuxp 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 tmuxp 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 pane in the session.

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


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