libtmux

libtmux wraps the tmux terminal multiplexer’s command-line interface behind a typed Python object model, so instead of shelling out to tmux ls and parsing text output, you work with real Server, Session, Window, and Pane objects that expose properties and methods mirroring tmux’s own concepts. Every object still exposes a raw .cmd() escape hatch for any tmux subcommand tmux supports, so the abstraction never becomes a ceiling.

The library is the foundation that tmuxp is built on, which means its object model has been exercised against real-world session-management workloads for years rather than existing as a theoretical API. It supports multiple tmux sockets and servers simultaneously, context managers for automatic session/window cleanup, and a bundled pytest plugin that spins up isolated tmux server fixtures for tests that need a real terminal multiplexer running.

Type coverage is comprehensive — the project runs mypy in strict mode across both src and tests — and the public API is documented with runnable doctest examples embedded directly in docstrings, which are executed as part of the test suite via --doctest-docutils-modules. This keeps the documentation from drifting out of sync with the actual behavior of the code.

What You Get

• Typed Server, Session, Window, and Pane classes that mirror tmux’s own object hierarchy
• A .cmd() escape hatch on every object for issuing arbitrary tmux commands with proper socket targeting
• Query and traversal helpers for filtering live sessions, windows, and panes by attribute
• Context managers that automatically clean up sessions and windows when a with block exits
• Support for multiple concurrent tmux sockets and servers from a single Python process
• A bundled pytest plugin providing isolated tmux server fixtures for integration testing

Common Use Cases

• Driving tmux programmatically from automation and deployment scripts instead of shelling out to the CLI
• Building higher-level session managers (as tmuxp does) on top of a stable, typed tmux API
• Writing integration tests for terminal applications using the pytest plugin’s isolated tmux fixtures
• Locating the current pane/window/session context from inside a running tmux pane via from_env()
• Scripting repeatable multi-pane development environment layouts

Under The Hood

Architecture libtmux is a thin, layered wrapper around the tmux binary: common.py defines the CmdMixin/CmdProtocol foundation that every domain object builds on, server.py’s Server class is the entry point that shells out via tmux_cmd and parses structured output through neo.py’s fetch_objs/parse_output, and Session, Window, and Pane (in their own modules) compose EnvironmentMixin and OptionsMixin to add environment-variable and tmux-option management on top of the shared command layer. Objects hold snapshots of tmux state (documented explicitly as such, e.g. Client’s docstring warns that session_id/window_id/pane_id are point-in-time reads, not live identity), and the object graph is intentionally shallow — Server owns Sessions, which own Windows, which own Panes — so a change to the core tmux_cmd/neo parsing layer would ripple through every domain object uniformly rather than requiring per-class fixes.

Tech Stack The library targets Python 3.10+ (tested through 3.14 and PyPy) with zero runtime dependencies beyond the standard library, keeping it lightweight enough to vendor into other tools like tmuxp. Development tooling is entirely uv-based (uv.lock present) with ruff for linting/formatting, mypy --strict for type checking, and a pytest-based suite (pytest-xdist, pytest-rerunfailures, pytest-mock) run via a justfile task runner. Docs are built with a custom Sphinx toolchain (gp-sphinx) and published to a dedicated libtmux.git-pull.com domain.

Code Quality The test suite spans 32 test files exercising each domain object plus internal helpers, and mypy strict mode is enforced across both src and tests, meaning test code itself must satisfy full type checking. Docstrings throughout the core modules embed runnable doctest examples that are executed as real tests via --doctest-docutils-modules, so the documentation cannot silently drift from actual behavior. CI runs a dedicated tests.yml workflow plus a separate docs.yml build check, and codecov tracks coverage on every run.

What Makes It Unique Rather than being a general subprocess wrapper, libtmux models tmux’s actual object hierarchy (server/session/window/pane) with typed classes and keeps a raw .cmd() escape hatch on every level, so it never forces users into an incomplete abstraction over tmux’s large command surface. Its pytest plugin is a distinguishing feature for a library in this niche — it turns “tests that need a real terminal multiplexer” into a first-class, isolated fixture rather than something every downstream project has to reinvent, and the fact that tmuxp itself is built on libtmux gives the abstraction unusually strong real-world validation for a project of its size.