or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

exceptions.mdindex.mdpane.mdserver.mdsession.mdutilities.mdwindow.md
tile.json

tessl/pypi-libtmux

Typed library that provides an ORM wrapper for tmux, a terminal multiplexer.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/libtmux@0.46.x

To install, run

npx @tessl/cli install tessl/pypi-libtmux@0.46.0

index.mddocs/

libtmux

libtmux is a typed Python library that provides an ORM wrapper for tmux, a terminal multiplexer. It offers a pythonic interface to manage tmux servers, sessions, windows, and panes programmatically, enabling developers to automate terminal workflows and build tmux-powered applications.

Package Information

  • Package Name: libtmux
  • Package Type: pypi
  • Language: Python
  • Installation: pip install libtmux

Core Imports

import libtmux
from libtmux import Server, Session, Window, Pane

Basic Usage

import libtmux

# Connect to tmux server
server = libtmux.Server()

# Create a new session
session = server.new_session(session_name="my_session", window_name="main")

# Create a new window
window = session.new_window(window_name="work")

# Split window into panes  
pane = window.split()

# Send commands to pane
pane.send_keys("echo 'Hello World'")
pane.send_keys("Enter")

# Get output from pane
output = pane.capture_pane()
print(output)

# Clean up
session.kill()

Architecture

libtmux follows tmux's hierarchical structure with context manager support for automatic cleanup:

  • Server: Top-level tmux server instance managing socket connections and global operations
  • Session: Collection of windows within a server, handling session-level configuration and environment
  • Window: Collection of panes within a session, managing layout and window-specific options
  • Pane: Individual terminal instance within a window, providing direct interaction with shell processes

All objects support both direct manipulation and context manager protocols for proper resource management.

Capabilities

Server Management

Server connection, lifecycle management, and global tmux operations. Handles socket connections, server status, and cross-session operations.

class Server:
    def __init__(
        self,
        socket_name: str | None = None,
        socket_path: str | pathlib.Path | None = None,
        config_file: str | None = None,
        colors: int | None = None,
        on_init: t.Callable[[Server], None] | None = None,
        socket_name_factory: t.Callable[[], str] | None = None,
        **kwargs: t.Any
    ) -> None: ...
    def is_alive(self) -> bool: ...
    def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
    def new_session(
        self,
        session_name: str | None = None,
        kill_session: bool = False,
        attach: bool = False,
        start_directory: StrPath | None = None,
        window_name: str | None = None,
        window_command: str | None = None,
        x: int | DashLiteral | None = None,
        y: int | DashLiteral | None = None,
        environment: dict[str, str] | None = None,
        *args: t.Any,
        **kwargs: t.Any
    ) -> Session: ...
    def has_session(self, target_session: str, exact: bool = True) -> bool: ...
    def kill_session(self, target_session: str | int) -> Server: ...

Server Management

Session Management

Session creation, configuration, and lifecycle operations. Manages session-level environment variables, options, and window collections.

class Session:
    server: Server
    def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
    def new_window(
        self,
        window_name: str | None = None,
        *,
        start_directory: StrPath | None = None,
        attach: bool = False,
        window_index: str = "",
        window_shell: str | None = None,
        environment: dict[str, str] | None = None,
        direction: WindowDirection | None = None,
        target_window: str | None = None
    ) -> Window: ...
    def kill(self, all_except: bool | None = None, clear: bool | None = None) -> None: ...
    def set_environment(self, name: str, value: str) -> Session: ...
    def show_environment(self, global_: bool = False) -> dict[str, str]: ...

Session Management

Window Management

Window operations, layout management, and pane organization. Handles window-specific options, layouts, and pane splitting operations.

class Window:
    server: Server
    def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
    def split(
        self,
        /,
        target: int | str | None = None,
        start_directory: StrPath | None = None,
        attach: bool = False,
        direction: PaneDirection | None = None,
        full_window_split: bool | None = None,
        zoom: bool | None = None,
        shell: str | None = None,
        size: str | int | None = None,
        environment: dict[str, str] | None = None
    ) -> Pane: ...
    def select_layout(self, layout: str | None = None) -> Window: ...
    def rename_window(self, new_name: str) -> Window: ...
    def kill(self, all_except: bool | None = None) -> None: ...

Window Management

Pane Management

Direct pane interaction, content capture, and command execution. Provides the primary interface for sending commands and retrieving output from terminal sessions.

class Pane:
    server: Server
    def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
    def send_keys(
        self,
        cmd: str,
        enter: bool | None = True,
        suppress_history: bool | None = False,
        literal: bool | None = False
    ) -> None: ...
    def capture_pane(
        self,
        start: t.Literal["-"] | int | None = None,
        end: t.Literal["-"] | int | None = None
    ) -> str | list[str]: ...
    def split(
        self,
        /,
        target: int | str | None = None,
        start_directory: StrPath | None = None,
        attach: bool = False,
        direction: PaneDirection | None = None,
        full_window_split: bool | None = None,
        zoom: bool | None = None,
        shell: str | None = None,
        size: str | int | None = None,
        environment: dict[str, str] | None = None
    ) -> Pane: ...
    def kill(self, all_except: bool | None = None) -> None: ...

Pane Management

Exception Handling

Comprehensive exception hierarchy for error handling and tmux-specific error conditions.

class LibTmuxException(Exception): ...
class TmuxSessionExists(LibTmuxException): ...
class TmuxCommandNotFound(LibTmuxException): ...
class TmuxObjectDoesNotExist(LibTmuxException): ...
class VersionTooLow(LibTmuxException): ...

Exception Handling

Utility Functions

Version checking, tmux compatibility, and helper functions for tmux operations.

def get_version() -> LooseVersion: ...
def has_minimum_version(raises: bool = True) -> bool: ...
def session_check_name(session_name: str | None) -> None: ...

Utilities

Types

Core Types

from typing import Dict, List, Optional, Union, Any
from pathlib import Path

StrPath = Union[str, Path]

class QueryList(list):
    """List-like interface with filtering capabilities."""
    def get(self, **kwargs): ...
    def filter(self, **kwargs): ...

Direction Enums

from enum import Enum

class PaneDirection(Enum):
    Above = "ABOVE"
    Below = "BELOW" 
    Left = "LEFT"
    Right = "RIGHT"

class WindowDirection(Enum):
    Before = "BEFORE"
    After = "AFTER"

class ResizeAdjustmentDirection(Enum):
    Up = "UP"
    Down = "DOWN"
    Left = "LEFT" 
    Right = "RIGHT"