Architecture

libtmux is a typed abstraction layer for tmux. It builds upon tmux’s concept of targets (-t) to direct commands against individual sessions, windows, and panes, and FORMATS — template variables tmux exposes to describe object properties.

Object Hierarchy

libtmux mirrors tmux’s object hierarchy as a typed Python ORM:

Server
└── Session
    └── Window
        └── Pane

Object

Child

Parent

Server

Session

None

Session

Window

Server

Window

Pane

Session

Pane

None

Window

TmuxRelationalObject acts as the base container connecting these relationships.

Internal Identifiers

tmux assigns unique IDs to sessions, windows, and panes. libtmux uses these — via TmuxMappingObject — to track objects reliably across state refreshes.

Object

Prefix

Example

Server

N/A

Uses socket-name / socket-path

Session

$

$13

Window

@

@3243

Pane

%

%5433

Core Objects

Each level wraps tmux commands and format queries:

  • Server — entry point, manages sessions, executes raw tmux commands

  • Session — manages windows within a session

  • Window — manages panes, handles layouts

  • Pane — terminal instance, sends keys and captures output

Data Flow

  1. User creates a Server (connects to a running tmux server)

  2. Queries use tmux format strings (libtmux.constants) to fetch state

  3. Results are parsed into typed Python objects

  4. Mutations dispatch tmux commands via the cmd() method

  5. Objects refresh state from tmux on demand

Module Map

Module

Role

libtmux.server

Server connection and session management

libtmux.session

Session operations

libtmux.window

Window operations and pane management

libtmux.pane

Pane I/O and capture

libtmux.common

Base classes, command execution

libtmux.neo

Modern dataclass-based query interface

libtmux.constants

Format string constants

libtmux.options

tmux option get/set

libtmux.hooks

tmux hook management

libtmux.exc

Exception hierarchy

Naming Conventions

tmux commands use dashes (new-window). libtmux replaces these with underscores (new_window) to follow Python naming conventions.

References