DOCSEARCHbyAlgolia
Submit Docs

tmuxp Documentation

repository·master·Indexed 26 days ago

https://github.com/tmux-python/tmuxp

A session manager for tmux that allows users to save and load complex layouts and configurations using YAML or JSON files. Powered by libtmux, tmuxp provides tools to freeze current sessions, convert configuration formats, and interactively manipulate the tmux environment via a Python shell. It requires tmux version 3.2 or newer.

Tokens
17.6K
Snippets
68
Records
140
Agent score
87%

What's inside tmuxp

  1. Compare tmuxp to other session managers

    master

    While tmuxp, tmuxinator, and teamocil all load tmux sessions from configuration files, tmuxp differs in the following ways:

    • Language: Written in Python (unlike tmuxinator which is Ruby).
    • Session Building: Uses the libtmux ORM layer instead of raw shell commands.
    • Format Support: Supports both JSON and YAML configuration formats.
    • Session Persistence: Can freeze running sessions back to a configuration file.

  3. Understand tmux hierarchy

    master

    tmux organizes work into a specific hierarchy:

    1. Server: The background process.
    2. Session: A collection of workspaces (similar to a desktop).
    3. Window: A single workspace within a session (similar to a virtual desktop).
    4. Pane: A subdivision of a window used to run multiple applications simultaneously (similar to an application window).

  4. Enable shell completion for tmuxp 1.17+

    master

    For tmuxp version 1.17 and newer, shell completion is powered by the shtab library. This library is not bundled with tmuxp and must be installed separately. Once installed, you can generate and install completion scripts for Bash, Zsh, or Tcsh using the shtab command and the tmuxp.cli.create_parser entrypoint.

    # 1. Install shtab
pip install shtab --user

# 2. Install completions (example for Bash)
shtab --shell=bash -u tmuxp.cli.create_parser \
  | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/TMUXP

  5. Configure custom workspace builders

    master

    A workspace builder converts an expanded workspace dictionary into a live tmux session. By default, tmuxp uses tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder. You can specify a different builder in your workspace YAML/JSON file using the workspace_builder key.

    Selecting a builder

    1. By dotted path: Provide a direct importable class path (e.g., module.attr or module:attr).
    2. By entry-point name: Use a short name if the builder is registered under the tmuxp.workspace_builders entry-point group (e.g., classic).
    3. Using trusted paths: If the builder is in a non-standard directory (like a local config folder), use workspace_builder_paths to tell tmuxp where to look. tmuxp will temporarily prepend these directories to sys.path during the build process.
    session_name: my-session
workspace_builder: my_tmuxp_builders.builders:CustomBuilder
# Or by entry-point name if registered:
# workspace_builder: mybuilder

workspace_builder_paths:
  - ~/.config/tmuxp/builders

  6. Lint, format, and type check tmuxp code

    master

    The project uses ruff for linting/formatting and mypy for type checking.

    Linting and Formatting

    • Lint: just ruff
    • Autofix linting errors: uv run ruff check . --fix --show-fixes
    • Format code: just ruff-format

    Type Checking

    • Run mypy: just mypy
    • Watch mypy for changes: just watch-mypy
    $ just ruff
$ uv run ruff check . --fix --show-fixes
$ just ruff-format
$ just mypy
$ just watch-mypy

  7. Write a custom workspace builder

    master

    To create a custom builder, the simplest approach is to subclass ClassicWorkspaceBuilder and override the build method.

    If writing a builder from scratch, it must implement the tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol contract, which includes:

    • A constructor accepting session_config, server, and optional plugins and callbacks (on_progress, on_before_script, on_script_output, on_build_event).
    • The build(session=None, append=False) method to create or populate the session.
    • The session attribute (a libtmux.Session instance).
    • session_exists() and find_current_attached_session() methods for CLI attach/append logic.
    • Support for the plugins list and their lifecycle hooks.
    • Invocation of on_* callbacks to ensure CLI progress displays remain accurate.
    from tmuxp.workspace.builder.classic import ClassicWorkspaceBuilder


class CustomBuilder(ClassicWorkspaceBuilder):
    """A builder that renames the session after building."""

    def build(self, session=None, append=False):
        super().build(session=session, append=append)
        self.session.rename_session(f"{self.session.name}-custom")

  11. Export a running tmux session with tmuxp freeze

    master

    Use the tmuxp freeze command to export a currently running tmux session into a workspace configuration file (.json or .yaml). This allows you to save the current state of your session for later restoration.

    When running the command, tmuxp will prompt you to choose between saving the state as a .json or .yaml file. If you do not specify a session name, it defaults to the session you are currently attached to.

  12. Structure a tmuxp workspace file

    master

    Workspace files follow a hierarchical structure mirroring tmux: session -> windows -> panes -> shell_command.

    Key components include:

    1. session_name: The name of the tmux session.
    2. windows: A list of window configurations.
    3. panes: A list of pane configurations within each window.
    4. shell_command: A list of commands to run in each pane.
    session_name: My session
windows:
- window_name: Window 1
  panes:
  - shell_command:
    - cmd: echo "pane 1"
  - shell_command:
    - cmd: echo "pane 2"