Traversal

libtmux provides convenient access to move around the hierarchy of sessions, windows and panes in tmux.

This is done by libtmux’s object abstraction of targets (the -t argument) and the permanent internal ID’s tmux gives to objects.

Open two terminals:

Terminal one: start tmux in a separate terminal:

$ tmux

Terminal two, python or ptpython if you have it:

$ python

Setup

First, create a test session:

>>> session = server.new_session()  # Create a test session using existing server

Server Level

View the server’s representation:

>>> server  
Server(socket_name=...)

Get all sessions in the server:

>>> server.sessions  
[Session($... ...)]

Get all windows across all sessions:

>>> server.windows  
[Window(@... ..., Session($... ...))]

Get all panes across all windows:

>>> server.panes  
[Pane(%... Window(@... ..., Session($... ...)))]

Session Level

Get first session:

>>> session = server.sessions[0]
>>> session  
Session($... ...)

Get windows in a session:

>>> session.windows  
[Window(@... ..., Session($... ...))]

Get active window and pane:

>>> session.active_window  
Window(@... ..., Session($... ...))

>>> session.active_pane  
Pane(%... Window(@... ..., Session($... ...)))

Window Level

Get a window and inspect its properties:

>>> window = session.windows[0]
>>> window.window_index  
'...'

Access the window’s parent session:

>>> window.session  
Session($... ...)
>>> window.session.session_id == session.session_id
True

Get panes in a window:

>>> window.panes  
[Pane(%... Window(@... ..., Session($... ...)))]

Get active pane:

>>> window.active_pane  
Pane(%... Window(@... ..., Session($... ...)))

Pane Level

Get a pane and traverse upwards:

>>> pane = window.panes[0]
>>> pane.window.window_id == window.window_id
True
>>> pane.session.session_id == session.session_id
True
>>> pane.server is server
True

Filtering and Finding Objects

Find windows by index:

>>> session.windows.filter(window_index=window.window_index)  
[Window(@... ..., Session($... ...))]

Get a specific pane by ID:

>>> window.panes.get(pane_id=pane.pane_id)  
Pane(%... Window(@... ..., Session($... ...)))

Checking Relationships

Check if objects are related:

>>> window in session.windows
True
>>> pane in window.panes
True
>>> session in server.sessions
True

Check if a window is active:

>>> window.window_id == session.active_window.window_id
True

Check if a pane is active:

>>> pane.pane_id == window.active_pane.pane_id
True