### Manual Virtualenv Setup

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Alternative setup using standard virtualenv and pip for editable installs.

```console
$ virtualenv .venv
```

```console
$ source .venv/bin/activate
```

```console
$ pip install -e .
```

```console
$ uv add --dev --editable .
```

--------------------------------

### Install tmuxp via pipx

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Example of a long shell command split across multiple lines for readability.

```console
$ pipx install \
    --suffix=@next \
    --pip-args '\--pre' \
    --force \
    'tmuxp'
```

--------------------------------

### Install from trunk

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/quickstart.md

Install the latest development version directly from the GitHub repository.

```console
$ pip install --user -e git+https://github.com/tmux-python/tmuxp.git#egg=tmuxp
```

```console
$ uv add "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master"
```

```console
$ uvx --from "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master" tmuxp
```

```console
$ pipx install --suffix=@master 'tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master' --force
```

--------------------------------

### Using a Plugin

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/plugins.md

To use a plugin, install it in your local python environment and add it to your tmuxp workspace file. Examples are provided for YAML and JSON workspace files.

```APIDOC
## Using a Plugin

To use a plugin, install it in your local python environment and add it to your tmuxp workspace file.

### Example Workspace files

````{tab} YAML

```yaml
# Example YAML workspace file with a plugin
session_name: plugin example
plugins:
  - my_plugin_module.plugin.MyTmuxpPlugin
# ... the rest of your config
```

````

````{tab} JSON

```json
// Example JSON workspace file with a plugin
{
  "session_name": "plugin example",
  "plugins": [
    "my_plugin_module.plugin.MyTmuxpPlugin"
  ]
  // ... the rest of your config
}
```

````
```

--------------------------------

### Before Scripts Configuration

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Executes setup scripts before tmux windows are created. Use `before_script` to prepare the environment, install dependencies, or perform other pre-session tasks. Ensures the session starts in a ready state.

```yaml
session_name: project-with-setup
start_directory: ~/myproject

# Run setup script before building session
before_script: ./scripts/setup-environment.sh

windows:
  - window_name: main
    panes:
      - shell_command:
          - npm start
```

--------------------------------

### Install tmuxp

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/index.md

Various methods to install the tmuxp package on your system.

```console
$ pip install tmuxp
```

```console
$ uv tool install tmuxp
```

```console
$ brew install tmuxp
```

--------------------------------

### Install tmuxp via Debian/Ubuntu

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Install the package using the system package manager.

```console
$ sudo apt install tmuxp
```

--------------------------------

### Set start directory

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Specify the working directory for a window.

```yaml
session_name: start-directory
windows:
- window_name: start directory
  start_directory: /tmp
  panes:
  - pwd
```

```json
{
  "session_name": "start-directory",
  "windows": [
    {
      "window_name": "start directory",
      "start_directory": "/tmp",
      "panes": [
        "pwd"
      ]
    }
  ]
}
```

--------------------------------

### Start Directory Configuration

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Demonstrates setting start directories at session, window, and pane levels. Absolute paths override relative paths and session defaults. Use for managing project context across different parts of your tmux session.

```yaml
session_name: project-workspace
# Session-level start directory (inherited by all windows/panes)
start_directory: /var/www/myproject

windows:
  - window_name: backend
    # Window-level directory (relative to session start_directory)
    start_directory: api
    panes:
      - shell_command:
          - python manage.py runserver
      - shell_command:
          - celery -A proj worker

  - window_name: frontend
    # Absolute path overrides session start_directory
    start_directory: /var/www/myproject/frontend
    panes:
      - shell_command:
          - npm start

  - window_name: logs
    start_directory: ~/  # Home directory
    panes:
      - shell_command:
          - tail -f /var/log/syslog
      # Pane-level start_directory
      - start_directory: /tmp
        shell_command:
          - ls -la
```

--------------------------------

### Automate Environment Bootstrapping

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Use before_script and shell_command_before to automate dependency installation and virtual environment activation.

```yaml
# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
windows:
- window_name: django project
  focus: true
  panes:
  - blank
  - pipenv run ./manage.py runserver
```

```yaml
# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
shell_command_before:
- '[ -d `pipenv --venv` ] && source `pipenv --venv`/bin/activate && reset'
windows:
- window_name: django project
  focus: true
  panes:
  - blank
  - ./manage.py runserver
```

--------------------------------

### Example tmuxp Configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

A sample YAML configuration file demonstrating how to define a tmux session with windows and panes.

```yaml
session_name: my-session
start_directory: ~/project
windows:
  - window_name: editor
    layout: main-vertical
    panes:
      - shell_command:
          - vim
      - shell_command:
          - git status

```

--------------------------------

### Example Plugin Workspace (YAML)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/plugins.md

Use this YAML format to specify plugins in your tmuxp workspace file. Ensure the plugin is installed in your local Python environment.

```yaml
session_name: plugin example
plugins:
  - my_plugin_module.plugin.MyTmuxpPlugin
# ... the rest of your config
```

--------------------------------

### Example Plugin Workspace (JSON)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/plugins.md

Use this JSON format to specify plugins in your tmuxp workspace file. Ensure the plugin is installed in your local Python environment.

```json
{
  "session_name": "plugin example",
  "plugins": [
    "my_plugin_module.plugin.MyTmuxpPlugin"
  ]
  # ... the rest of your config
}
```

--------------------------------

### Install ipdb via uvx

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/shell.md

Perform a pipx-style ad hoc install of ipdb using uvx.

```console
$ uvx --from ipdb ipdb3 --help
```

--------------------------------

### Install tmuxp via uv

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Add tmuxp as a dependency to a project managed by uv.

```console
$ uv add tmuxp
```

--------------------------------

### Install tmuxp via Nix

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Install tmux and tmuxp using the Nix package manager.

```console
$ [[ -z $(which tmux) ]] && (nix-env -i tmux && nix-env -i tmuxp) || nix-env -i tmuxp
```

--------------------------------

### Install developmental releases

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Install pre-release versions of tmuxp using various package managers.

```console
pip install --user --upgrade --pre tmuxp
```

```console
uv add 'tmuxp>=1.10.0b1'
```

```console
uvx tmuxp
```

```console
pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
```

--------------------------------

### Load Tmuxp Configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Examples of loading tmuxp configurations using YAML or JSON formats.

```yaml
{literalinclude} ../../.tmuxp.yaml
:language: yaml
```

```json
{literalinclude} ../../.tmuxp.json
:language: json
```

--------------------------------

### Install tmuxp via Homebrew

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Install the package on macOS using Homebrew.

```console
$ brew install tmuxp
```

--------------------------------

### Run tmuxp with uvx

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Execute tmuxp without a global installation using uvx.

```console
$ uvx tmuxp
```

--------------------------------

### Install tmuxp via pip

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Install the package using pip for the current user.

```console
$ pip install --user tmuxp
```

--------------------------------

### Run ruff for formatting, linting, and import sorting (manual setup)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Execute ruff for code formatting, linting, and sorting imports when not using uv. This command checks the entire project.

```console
$ ruff check .
```

--------------------------------

### tmuxp Recipes

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/index.md

Provides a collection of ready-to-use command invocations and examples for common tmuxp tasks.

```APIDOC
## Recipes

### Description

Copy-pasteable command invocations.

### Method

Reference

### Endpoint

`tmuxp recipes`
```

--------------------------------

### Configure shell completions for tmuxp 1.17+

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/completion.md

Generate and install completion scripts for different shells using shtab.

```console
$ shtab --shell=bash -u tmuxp.cli.create_parser \
  | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/TMUXP
```

```console
$ shtab --shell=zsh -u tmuxp.cli.create_parser \
  | sudo tee /usr/local/share/zsh/site-functions/_TMUXP
```

```console
$ shtab --shell=tcsh -u tmuxp.cli.create_parser \
  | sudo tee /etc/profile.d/TMUXP.completion.csh
```

--------------------------------

### Changelog Format Example

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/releasing.md

The standard format for entries in the CHANGES file, including version, date, and categorized sections for new features, bug fixes, and breaking changes.

```text
tmuxp <version> (<date>)
------------------------

### What's new

- Description of feature (#issue)

### Bug fixes

- Description of fix (#issue)

### Breaking changes

- Description of break, migration path (#issue)
```

--------------------------------

### Logger Setup in Library Code

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

In library modules, use `logging.getLogger(__name__)` and add a `NullHandler` in `__init__.py`. Avoid configuring handlers, levels, or formatters in library code.

```python
import logging

logger = logging.getLogger(__name__)

# In library's __init__.py:
# logger.addHandler(logging.NullHandler())
```

--------------------------------

### Define a tmux session configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Example YAML configuration for a 4-pane tiled layout with custom shell commands.

```yaml
session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/ # run as a first command in all panes
    panes:
      - shell_command: # pane no. 1
          - cd /var/log # run multiple commands in this pane
          - ls -al | grep \.log
      - echo second pane # pane no. 2
      - echo third pane # pane no. 3
      - echo fourth pane # pane no. 4
```

--------------------------------

### Install shtab dependency

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/completion.md

Install the shtab library required for completions in tmuxp 1.17+.

```console
$ pip install shtab --user
```

```console
$ uv add --dev shtab
```

```console
$ uvx shtab --help
```

--------------------------------

### Multi-Pane Tiled Layout

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Sets up a development environment with a 4-pane tiled layout. Includes commands to change directory and run applications in each pane. Useful for complex development setups.

```yaml
# 4-pane tiled layout
session_name: dev-environment
windows:
  - window_name: development
    layout: tiled
    shell_command_before:
      - cd ~/project
    panes:
      - shell_command:
          - vim src/main.py
      - shell_command:
          - npm run watch
      - shell_command:
          - tail -f logs/app.log
      - shell_command:
          - htop
```

--------------------------------

### Start a new tmux session

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

This command starts a new tmux session. It's the most basic command to launch tmux.

```bash
$ tmux
```

--------------------------------

### Format code using ruff format (manual setup)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Format code using ruff's formatter without uv. This command applies code style changes to the entire project.

```console
$ ruff format .
```

--------------------------------

### Define a tmuxp workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/index.md

Example YAML configuration for defining a tmux session with named windows and shell commands.

```yaml
session_name: my-project
windows:
  - window_name: editor
    panes:
      - shell_command:
          - vim
      - shell_command:
          - git status
```

--------------------------------

### Install ipdb for debugger integration

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/shell.md

Install ipdb for debugger integration with tmuxp shell. Supports PEP 553's PYTHONBREAKPOINT.

```console
$ pip install --user ipdb
```

--------------------------------

### Watch and Run Tests on File Changes

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Starts a development server that watches for file changes and runs tests automatically. An alternative to `ptw`.

```bash
just start

```

```bash
just watch-test

```

--------------------------------

### Smallest possible tmuxp workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

The most basic tmuxp workspace file. This example is useful for understanding the minimum required configuration.

```yaml
session_name: Minimal
windows:
- panes:
  - shell_command:
    - cmd: "echo hello world"
```

--------------------------------

### Verify tmuxp installation

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/troubleshooting.md

Check if the tmuxp executable is available in your current system PATH.

```console
$ which tmuxp
```

--------------------------------

### Basic Workspace Configuration

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Defines a minimal tmuxp workspace with a session name and two windows, each containing panes. Use this for simple session setups.

```yaml
# ~/.tmuxp/minimal.yaml
session_name: my-project
windows:
  - window_name: editor
    panes:
      - shell_command:
          - vim
  - window_name: shell
    panes:
      - pane  # Empty pane with shell
```

--------------------------------

### Define shell commands for a pane

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

You can specify commands to run within each pane. This example shows how to define multiple commands for a single pane.

```yaml
windows:
  panes:
    - shell_command:
        - cmd: echo "pane 1 - cmd 1"
          # command options
        - cmd: echo "pane 1 - cmd 2"
          # command options
```

--------------------------------

### Define a tmuxp session configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/AGENTS.md

Example YAML configuration for defining a tmux session with a specific layout and shell commands.

```yaml
session_name: my-session
start_directory: ~/project
windows:
  - window_name: editor
    layout: main-vertical
    panes:
      - shell_command:
          - vim
      - shell_command:
          - git status
```

--------------------------------

### Define multiple windows in a workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

A workspace file can contain multiple windows, each with its own name and panes. This example shows how to define two windows.

```yaml
windows:
  - window_name: Window 1
    panes: ...
    # window settings
  - window_name: Window 2
    panes: ...
    # window settings
```

--------------------------------

### Run mypy for static type checking (manual setup)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Perform static type checking on the project using mypy without uv. This command helps identify type errors in the codebase.

```console
$ mypy .
```

--------------------------------

### Define panes within a window

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

Each window can have multiple panes. This example shows the structure for defining panes within a window.

```yaml
windows:
  panes:
    -  # pane settings
    -  # pane settings
```

--------------------------------

### Set Window Options After Pane Creation

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Apply window options like `synchronize-panes` after panes have been created. This is useful for enabling features that affect multiple panes simultaneously after their initial setup.

```yaml
session_name: my_session
windows:
  - window_name: my_window
    layout: main-vertical
    panes:
      - shell_command:
        - echo "pane 1"
      - shell_command:
        - echo "pane 2"
    window_options:
      synchronize-panes: true

```

```json
{
  "session_name": "my_session",
  "windows": [
    {
      "window_name": "my_window",
      "layout": "main-vertical",
      "panes": [
        {
          "shell_command": [
            "echo \"pane 1\""
          ]
        },
        {
          "shell_command": [
            "echo \"pane 2\""
          ]
        }
      ],
      "window_options": {
        "synchronize-panes": true
      }
    }
  ]
}
```

--------------------------------

### Custom Progress Format String

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Use a custom format string with available tokens to display session, window, and pane progress information. The example shows how to include session name, progress bar, and overall percentage.

```console
$ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject
```

--------------------------------

### Build and Serve Documentation

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Commands for building, serving locally, and developing documentation with auto-reloading.

```bash
just build-docs

```

```bash
just serve-docs

```

```bash
just dev-docs

```

```bash
just start-docs

```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Initial steps to download the source code and enter the project directory.

```console
$ git clone git@github.com:tmux-python/tmuxp.git
```

```console
$ cd tmuxp
```

--------------------------------

### Developing a Plugin

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/plugins.md

tmuxp expects plugins to be a class within a `plugin` submodule of an installed Python module. This section details the structure, packaging, and an example implementation of a tmuxp plugin.

```APIDOC
## Developing a Plugin

tmuxp expects all plugins to be a class within a python submodule named `plugin` that is within a python module that is installed in the local python environment. A plugin interface is provided by tmuxp to inherit.

### Project Structure

```console
python_module
├── tmuxp_plugin_my_plugin_module
│   ├── __init__.py
│   └── plugin.py
└── pyproject.toml  # Python project configuration file
```

### Publishing Plugins

When publishing plugins to pypi, tmuxp advocates for standardized naming: `tmuxp-plugin-{your-plugin-name}` to allow for easier searching.

### `pyproject.toml` Example

```toml
[project]
name = "tmuxp-plugin-my-tmuxp-plugin"
version = "0.0.2"
description = "An example tmuxp plugin."
authors = ["Author Name <author.name@<domain>.com>"]
requires-python = ">=3.8,<4.0"
dependencies = [
  "tmuxp^=1.7.0"
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

### `plugin.py` Example

```python
from tmuxp.plugin import TmuxpPlugin
import datetime

class MyTmuxpPlugin(TmuxpPlugin):
    def __init__(self):
        """
        Initialize my custom plugin.
        """
        # Optional version dependency configuration. See Plugin API docs
        # for all supported config parameters
        config = {
            'tmuxp_min_version': '1.6.2'
        }

        TmuxpPlugin.__init__(
            self,
            plugin_name='tmuxp-plugin-my-tmuxp-plugin',
            **config
        )

    def before_workspace_builder(self, session):
        session.rename_session('my-new-session-name')

    def reattach(self, session):
        now = datetime.datetime.now().strftime('%Y-%m-%d')
        session.rename_session('session_{}'.format(now))
```
```

--------------------------------

### Load from a project directory

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/recipes.md

Loads a workspace configuration from the current directory.

```console
$ tmuxp load .
```

--------------------------------

### Load configuration via direct path

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Load a configuration file using a direct path argument.

```console
$ tmuxp load [filename]
```

--------------------------------

### Use Shorthand Syntax for Configurations

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Utilize compact syntax for defining shell commands, multiple commands, and empty panes.

```yaml
session_name: shorthand-examples
windows:
  # Minimal window with single pane
  - window_name: simple
    panes:
      - echo "hello world"  # String shorthand for shell_command

  # Multiple commands as list
  - window_name: multi-command
    panes:
      - - cd /var/log
        - tail -f syslog
      - htop  # Single command

  # Empty/blank panes
  - window_name: empty-panes
    panes:
      - pane   # Keyword for empty pane
      - blank  # Alternative keyword
      -        # Null/empty also works
```

--------------------------------

### Verify tmux installation

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/troubleshooting.md

Check the installed version of tmux to ensure it meets the minimum requirement of 3.2a.

```console
$ tmux -V
```

--------------------------------

### tmuxp Main Command

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/index.md

The main `tmuxp` command serves as the entry point for all operations. Subcommands are used to perform specific tasks such as loading sessions, managing configurations, and interacting with tmux.

```APIDOC
## Main command

The `tmuxp` command is the entry point for all tmuxp operations. Use subcommands to load sessions, manage configurations, and interact with tmux.

### Command

```
tmuxp [subcommand]
```

### Subcommands

- **load**: Load tmux sessions from workspace configs.
- **shell**: Interactive Python shell with tmux context.
- **freeze**: Export running sessions to config files.
- **convert**: Convert between YAML and JSON formats.
- **ls**: List tmux sessions.
- **search**: Search for tmux sessions.
- **edit**: Edit tmux session configurations.
- **import**: Import tmux sessions.
- **debug-info**: Collect diagnostic information.
- **completion**: Shell completion for tmuxp commands.

### See Also

- **Exit Codes**: For scripting and automation.
- **Recipes**: Copy-pasteable command invocations.
```

--------------------------------

### Upgrade tmuxp

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/quickstart.md

Commands to update existing tmuxp installations.

```console
$ pip install --user --upgrade tmuxp
```

```console
$ uv lock --upgrade-package tmuxp
$ uv sync
```

--------------------------------

### Load user-based or direct file configurations

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Load configurations by name from the ~/.tmuxp directory or by providing a direct file path.

```console
$ tmuxp load myconfig
```

```console
$ tmuxp load ./myfile.yaml
```

```console
$ tmuxp load /abs/path/to/myfile.yaml
```

```console
$ tmuxp load ~/myfile.yaml
```

--------------------------------

### tmuxp debug-info

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/index.md

Collects and displays diagnostic information about the tmuxp environment and tmux setup.

```APIDOC
## tmuxp debug-info

### Description

Diagnostic information for debugging.

### Method

CLI Command

### Endpoint

`tmuxp debug-info`
```

--------------------------------

### Load a workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/recipes.md

Loads a workspace configuration file.

```console
$ tmuxp load my-workspace.yaml
```

--------------------------------

### Load project-based configurations

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Load tmuxp configurations from directories containing .tmuxp.yaml or .tmuxp.json files.

```console
$ tmuxp load .
```

```console
$ tmuxp load ../
```

```console
$ tmuxp load path/to/folder/
```

```console
$ tmuxp load /path/to/folder/
```

--------------------------------

### Get System Information with tmuxp debug-info

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Prints diagnostic information for troubleshooting tmuxp. Can output information as JSON.

```bash
tmuxp debug-info
```

```bash
tmuxp debug-info --json
```

--------------------------------

### Load tmuxp workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/quickstart.md

Commands to load session configurations from files.

```console
$ tmuxp load example.yaml
```

```console
$ tmuxp load example.yaml anothersession.yaml
```

--------------------------------

### Configure logging for load command

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Redirect output to a log file and optionally set the global log level.

```console
$ tmuxp load [filename] --log-file [log_filename]
```

```console
$ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]
```

--------------------------------

### Configure Environment with uv

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Commands to synchronize dependencies and execute commands within the managed environment.

```console
$ uv sync --all-extras --dev
```

```console
$ uv sync --all-extras --dev --upgrade
```

```console
$ uv run [command]
```

--------------------------------

### Set TMUXP_CONFIGDIR

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/environmental-variables.md

Sets the directory for tmuxp configuration files. This example shows loading a session with a custom config directory.

```bash
TMUXP_CONFIGDIR=$HOME/.mytmuxpconfigdir tmuxp load cpython
```

--------------------------------

### Watch all tests on file edit

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Automatically re-run all tests when any .py file is edited. This requires the 'entr(1)' utility to be installed.

```console
$ make watch_test
```

--------------------------------

### Focus windows and panes

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Use focus: true to select specific windows or panes upon loading.

```yaml
session_name: focus-window-and-panes
windows:
- window_name: focus-window
  focus: true
  panes:
  - pwd
  - pwd
- window_name: focus-pane
  panes:
  - pwd
  - focus: true
    shell_command:
    - pwd
```

```json
{
  "session_name": "focus-window-and-panes",
  "windows": [
    {
      "window_name": "focus-window",
      "focus": true,
      "panes": [
        "pwd",
        "pwd"
      ]
    },
    {
      "window_name": "focus-pane",
      "panes": [
        "pwd",
        {
          "focus": true,
          "shell_command": [
            "pwd"
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Split Window into Panes

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

Use this command to split the current pane into two. Optionally specify a starting directory or a shell command.

```console
tmux split-window [-c start-directory] <shell-command>
```

--------------------------------

### Run ruff for formatting, linting, and import sorting (uv)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Execute ruff using uv for code formatting, linting, and sorting imports. This command checks the entire project.

```console
$ uv run ruff
```

--------------------------------

### Load a project-specific workspace from the root

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

When a `.tmuxp.yaml` or `.tmuxp.json` file exists in the project's root directory, you can load it by specifying the directory path.

```console
$ tmuxp load ./
```

--------------------------------

### Load a tmux workspace file

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

Use the `tmuxp load` command followed by the path to your workspace file to launch a tmux session.

```console
$ tmuxp load ./path/to/file
```

--------------------------------

### Define Multi-line Shell Commands

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Use YAML's multiline syntax to execute multiple shell commands within a single pane or session setup.

```yaml
session_name: my project
shell_command_before:
- >
  [ -d `.venv/bin/activate` ] &&
  source .venv/bin/activate &&
  reset
- sleep 1
windows:
- window_name: first window
  layout: main-horizontal
  focus: true
  panes:
  - focus: True
  - blank
  - >
    uv run ./manage.py migrate &&
    npm -C js run start
  - uv run ./manage.py runserver
  options:
    main-pane-height: 35
```

--------------------------------

### Watch ruff checks on file edit

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Automatically run ruff checks when any file is edited. This requires 'entr(1)' to be installed and is useful for continuous linting and formatting.

```console
$ make watch_ruff
```

--------------------------------

### Load a tmuxp workspace

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/index.md

Command to load a previously defined tmuxp configuration file.

```console
$ tmuxp load my-project.yaml
```

--------------------------------

### Import teamocil configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/import.md

Converts teamocil YAML or JSON configuration files to the tmuxp format.

```console
$ tmuxp import teamocil /path/to/file.yaml
```

```console
$ tmuxp import teamocil /path/to/file.json
```

--------------------------------

### Run tests via uv

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Standard commands for executing tests and coverage reports.

```console
$ uv run pytest
```

```console
$ uv run pytest --cov
```

--------------------------------

### Watch mypy checks on file edit

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Automatically run mypy checks when any file is edited. This requires 'entr(1)' to be installed and is useful for continuous static type checking.

```console
$ make watch_mypy
```

--------------------------------

### Import Configurations from Other Tools with tmuxp import

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Imports and converts workspace configurations from tmuxinator or teamocil format to tmuxp format.

```bash
tmuxp import tmuxinator ~/.tmuxinator/project.yml
```

```bash
tmuxp import teamocil ~/.teamocil/project.yml
```

--------------------------------

### Pipe Shell Command to Status Line

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

This example shows how to pipe the output of a shell command into the tmux status line. Ensure `status-interval` is set appropriately, e.g., to 1.

```console
$(shell-command)
```

--------------------------------

### Load a workspace from an absolute path

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

Load a workspace configuration file using its absolute path.

```console
$ tmuxp load /opt/myapp/favorites.yaml
```

--------------------------------

### Example Git Commit Message

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Use this format for commit messages to provide clear context on changes. The 'why' and 'what' sections are crucial for understanding the necessity and impact of the commit.

```gitcommit
Pane(feat[send_keys]): Add support for literal flag

why: Enable sending literal characters without tmux interpretation
what:
- Add literal parameter to send_keys method
- Update send_keys to pass -l flag when literal=True
- Add tests for literal key sending
```

--------------------------------

### Load Workspace via CLI

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Load a tmuxp workspace file directly from the command line.

```console
$ tmuxp load ~/workspaces/myproject.yaml
```

--------------------------------

### Load a workspace from a relative path

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/index.md

Load a workspace configuration file located at a relative path from the current directory.

```console
$ tmuxp load ./favorites.yaml
```

--------------------------------

### Format code with ruff

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/code-style.md

Run the ruff formatter across the project directory.

```console
$ uv run ruff format .
```

--------------------------------

### List available workspaces

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/recipes.md

Displays a list of all available tmuxp workspaces.

```console
$ tmuxp ls
```

--------------------------------

### Execute Bootstrap Scripts

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Run scripts before session building using before_script. Ensure the script is executable and relative to the configuration file root.

```yaml
session_name: my session
before_script: ./bootstrap.py
# ... the rest of your workspace
```

```json
{
    "session_name": "my session",
    "before_script": "./bootstrap.py"
}
```

```yaml
session_name: another example
before_script: /absolute/path/this.sh # abs path to shell script
# ... the rest of your workspace
```

```json
{
    "session_name": "my session",
    "before_script": "/absolute/path/this.sh"
}
```

--------------------------------

### Pause Command Execution in tmuxp

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Utilize `sleep_before` and `sleep_after` to introduce delays before and after command execution. This is a blocking operation and useful for commands that require terminal breathing room, such as virtual environment setup or launching TUI applications. Equivalent to `time.sleep`.

```yaml
session_name: my_session
windows:
  - window_name: my_window
    layout: main-vertical
    panes:
      - shell_command:
        - echo "hello"
        - echo "world"
        sleep_before: 1
        sleep_after: 1

```

```yaml
session_name: my_session
windows:
  - window_name: my_window
    layout: main-vertical
    panes:
      - shell_command:
        - echo "hello"
        - echo "world"
        sleep_before: 1
        sleep_after: 1

```

```yaml
session_name: my_session
windows:
  - window_name: my_window
    layout: main-vertical
    panes:
      - shell_command:
        - echo "hello"
        - echo "world"
        sleep_before: 1
        sleep_after: 1

```

```yaml
session_name: my_session
windows:
  - window_name: my_window
    layout: main-vertical
    panes:
      - shell_command:
        - echo "hello"
        - echo "world"
        sleep_before: 1
        sleep_after: 1

```

--------------------------------

### tmuxp ls

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/ls.md

Lists all available workspace configurations found in the local project and global tmuxp configuration directories.

```APIDOC
## tmuxp ls

### Description
List available workspace configurations from your local project and global tmuxp directories.

### Command
`tmuxp ls`
```

--------------------------------

### Automate development environments

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/workflows.md

Commands to capture an existing tmux layout and restore it later.

```console
tmuxp freeze my-session
```

```console
tmuxp load my-workspace.yaml
```

--------------------------------

### Convert workspace formats

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/recipes.md

Converts configuration files between YAML and JSON formats.

```console
$ tmuxp convert my-workspace.yaml
```

```console
$ tmuxp convert my-workspace.json
```

--------------------------------

### Execute tmuxp via uvx

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Run tmuxp directly without manual environment activation.

```console
$ uvx tmuxp
```

```console
$ tmuxp
```

--------------------------------

### Using Fixtures in Doctests

Source: https://github.com/tmux-python/tmuxp/blob/master/CLAUDE.md

Demonstrates how to use fixtures like 'server' and 'session' within doctests. Use ellipsis for variable output. Doctests must execute and not be commented out.

```python
>>> from tmuxp.workspace.builder import WorkspaceBuilder
>>> config = {'session_name': 'test', 'windows': [{'window_name': 'main'}]}
>>> builder = WorkspaceBuilder(session_config=config, server=server)  # doctest: +ELLIPSIS
>>> builder.build()
>>> builder.session.name
'test'
```

--------------------------------

### Swap Window with Destination

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

Use this command to swap the current window with a specified destination window.

```console
tmux swap-window [-t dst-window]
```

--------------------------------

### Programmatic session control with libtmux

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/library-vs-cli.md

Use the libtmux Python library to create sessions, windows, and panes dynamically.

```python
import libtmux

server = libtmux.Server()
session = server.new_session("my-project")
window = session.new_window("editor")
pane = window.split()
pane.send_keys("vim .")
```

--------------------------------

### Define blank panes

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/configuration/examples.md

Use null, 'blank', or 'pane' to create empty panes without commands.

```yaml
session_name: blank-panes
windows:
- window_name: blank panes
  panes:
  - null
  - blank
  - pane
  - ''
```

```json
{
  "session_name": "blank-panes",
  "windows": [
    {
      "window_name": "blank panes",
      "panes": [
        null,
        "blank",
        "pane",
        ""
      ]
    }
  ]
}
```

--------------------------------

### Load multiple sessions

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/load.md

Initialize multiple sessions simultaneously, with the final session attached by default.

```console
$ tmuxp load [filename1] [filename2] ...
```

--------------------------------

### CLI Commands Overview

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/internals/api/cli/index.md

This section lists the available CLI commands for tmuxp. Please be aware that internal APIs are not covered by version policies and may change without notice. For stabilized APIs, please file an issue.

```APIDOC
## CLI Commands

:::{warning}
Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!

If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues).
:::

## Available Commands

- `convert`
- `debug_info`
- `edit`
- `freeze`
- `import_config`
- `load`
- `ls`
- `progress`
- `search`
- `shell`
- `utils`
```

--------------------------------

### Load user-level configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Load a configuration file located in the standard tmuxp config directories.

```console
$ tmuxp load mysession
```

--------------------------------

### Import tmuxinator configuration

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/import.md

Converts tmuxinator YAML or JSON configuration files to the tmuxp format.

```console
$ tmuxp import tmuxinator /path/to/file.yaml
```

```console
$ tmuxp import tmuxinator /path/to/file.json
```

--------------------------------

### View tmux manual page

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

Use this command in a terminal to display the formatted text documentation for the tmux manual file.

```console
$ nroff -mdoc tmux.1|less
```

--------------------------------

### Process and Convert Configurations

Source: https://context7.com/tmux-python/tmuxp/llms.txt

Load, expand, and validate workspace configurations, including conversion between YAML and JSON formats.

```python
from pathlib import Path
from tmuxp._internal.config_reader import ConfigReader
from tmuxp.workspace import loader

# Load from file
config = ConfigReader._from_file(Path("./myworkspace.yaml"))

# Expand shell variables and shorthand syntax
expanded = loader.expand(config, cwd="/home/user/projects")

# Trickle down inherited values (session -> window -> pane)
final_config = loader.trickle(expanded)

# Convert between formats
reader = ConfigReader(final_config)
yaml_output = reader.dump(fmt="yaml", indent=2, default_flow_style=False)
json_output = reader.dump(fmt="json", indent=2)

print(yaml_output)
```

--------------------------------

### Configure custom config directory

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/quickstart.md

Set the configuration directory for tmuxp via environment variables.

```console
$ TMUXP_CONFIGDIR=$HOME/.tmuxpmoo tmuxp load cpython
```

```console
export TMUXP_CONFIGDIR=$HOME/.yourconfigdir/tmuxp
```

--------------------------------

### tmuxp search

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/cli/search.md

Command-line interface documentation for searching tmuxp workspace configurations.

```APIDOC
## CLI Command: tmuxp search

### Description
Search for workspace configurations by name or content across your tmuxp directories.

### Usage
`tmuxp search [OPTIONS]`

### Parameters
- **name** (string) - Optional - Search for configurations by name.
- **content** (string) - Optional - Search for configurations by content.
```

--------------------------------

### tmuxp.cli.utils Module

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/internals/api/cli/utils.md

Provides utility functions for the tmuxp command-line interface, including session management and configuration handling.

```APIDOC
## Module: tmuxp.cli.utils

### Description
This module contains helper functions and utilities used by the tmuxp CLI to interact with tmux sessions, parse configuration files, and manage workspace environments.

### Usage
These utilities are intended for internal use within the tmuxp CLI package to ensure consistent behavior across different commands.
```

--------------------------------

### tmuxp convert CLI

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/internals/api/cli/convert.md

Documentation for the tmuxp convert command used to transform configuration files.

```APIDOC
## CLI Command: tmuxp convert

### Description
The convert command is part of the tmuxp CLI, located in `tmuxp.cli.convert`. It is used to convert tmuxp configuration files between different formats.

### Usage
`tmuxp convert <config_file>`

### Parameters
#### Positional Arguments
- **config_file** (string) - Required - The path to the tmuxp configuration file to be converted.
```

--------------------------------

### Tag Release

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/releasing.md

Create a Git tag for the new release. Replace <version> with the new version number.

```console
git tag v<version>
```

--------------------------------

### tmuxp API Overview

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/internals/api/index.md

This section outlines the core modules available in the tmuxp API for managing tmux workspaces and internal configurations.

```APIDOC
## tmuxp API Modules

### Description
The tmuxp API is organized into several modules that handle different aspects of tmux automation, including workspace definitions, plugin management, and shell utilities.

### Modules
- **workspace**: Handles the loading and management of tmuxp YAML/JSON workspace configurations.
- **cli**: Interfaces for the command-line entry points.
- **plugin**: Base classes and utilities for extending tmuxp functionality.
- **shell**: Utilities for executing shell commands within tmux sessions.
- **util**: Helper functions for internal operations.
- **types**: Type definitions for static analysis and API consistency.
```

--------------------------------

### Plugin Configuration (pyproject.toml)

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/topics/plugins.md

This TOML file configures your Python package, including project metadata and dependencies. Ensure 'tmuxp' is listed as a dependency.

```toml
[project]
name = "tmuxp-plugin-my-tmuxp-plugin"
version = "0.0.2"
description = "An example tmuxp plugin."
authors = ["Author Name <author.name@<domain>.com>"]
requires-python = ">=3.8,<4.0"
dependencies = [
  "tmuxp^=1.7.0"
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

--------------------------------

### Format code using make command

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/project/contributing.md

Format code using ruff's formatter via the make command. This is a convenient shortcut for the ruff format command.

```console
$ make ruff_format
```

--------------------------------

### Launch Interactive Python Console with tmuxp

Source: https://github.com/tmux-python/tmuxp/blob/master/README.md

Launches an interactive Python console preloaded with libtmux objects for the attached server, session, and window. Supports PEP 553 breakpoint() and direct commands via -c.

```console
$ tmuxp shell

(Pdb) server
<libtmux.server.Server object at 0x7f7dc8e69d10>
(Pdb) server.sessions
[Session($1 your_project)]
(Pdb) session
Session($1 your_project)
(Pdb) session.name
'your_project'
(Pdb) window
Window(@3 1:your_window, Session($1 your_project))
(Pdb) window.name
'your_window'
(Pdb) window.panes
[Pane(%6 Window(@3 1:your_window, Session($1 your_project)))
(Pdb) pane
Pane(%6 Window(@3 1:your_window, Session($1 your_project))
```

```console
$ tmuxp shell -c 'print(window.name)'
my_window
```

```console
$ tmuxp shell -c 'print(window.name.upper())'
MY_WINDOW
```

--------------------------------

### Select Window by Number

Source: https://github.com/tmux-python/tmuxp/blob/master/docs/about_tmux.md

Use this command to select a specific window by its number.

```console
tmux select-window
```