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
└── Client (attached view)

Object

Child

Parent

Server

Session, Client

None

Session

Window

Server

Window

Pane

Session

Pane

None

Window

Client

None

Server

TmuxRelationalObject acts as the base container connecting these relationships.

Client is a view, not part of the ownership chain: each attached terminal points at a Session/Window/Pane it is currently displaying, but is not owned by them. See Clients for the view- vs-identity distinction.

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

  • Client — attached terminal viewing a session, window, and pane

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

Attached-client view and live-attachment lookup

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¶