tmuxp Documentation

Index Copy Section

(index)=

tmuxp

Session manager for tmux. Load, freeze, and convert tmux sessions through
YAML/JSON configuration files. Powered by libtmux.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Quickstart
:link: quickstart
:link-type: doc
Install and run your first command.
:::

:::{grid-item-card} CLI Reference
:link: cli/index
:link-type: doc
Every command, flag, and option.
:::

:::{grid-item-card} Configuration
:link: configuration/index
:link-type: doc
Config format, examples, and environment variables.
:::

::::

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Topics
:link: topics/index
:link-type: doc
Workflows, plugins, and troubleshooting.
:::

:::{grid-item-card} Contributing
:link: project/index
:link-type: doc
Internals, development setup, and release process.
:::

::::

Install Copy Chapter

$ pip install tmuxp

$ uv tool install tmuxp

$ brew install tmuxp

See Quickstart for all installation methods and first steps.

Load a workspace Copy Chapter

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

$ tmuxp load my-project.yaml

:width: 888
:height: 589
:loading: lazy

:hidden:

quickstart
cli/index
configuration/index
topics/index
internals/index
project/index
history

:hidden:
:caption: More

about_tmux
migration
glossary
MCP <https://libtmux-mcp.git-pull.com>
GitHub <https://github.com/tmux-python/tmuxp>

Quickstart Copy Section

(quickstart)=

Quickstart

tmuxp launches a whole tmux workspace — its windows, panes, and the commands
inside them — from a single YAML or JSON file. Install it, write one file, and
{ref}tmuxp load <cli-load> builds the session and drops you into it. This page
takes you from nothing to a running session.

Installation Copy Chapter

Ensure you have at least tmux >= 3.2 and python >= 3.10.

$ pip install --user tmuxp

If you manage dependencies with uv inside a project environment, add tmuxp to
your lockfile instead:

$ uv add tmuxp

To run tmuxp without installing it globally — the way you'd use pipx — invoke
it through uvx:

$ uvx tmuxp

Upgrade to the latest release with:

$ pip install --user --upgrade tmuxp

Within a uv-managed project, upgrade by refreshing the lockfile and syncing:

$ uv lock --upgrade-package tmuxp

$ uv sync

Then install {ref}completion.

Homebrew users can install it with:

$ brew install tmuxp

(developmental-releases)=

Developmental releases Copy Section

New versions of tmuxp are published to PyPI as alpha, beta, or release
candidates. Their version carries an a1, b1, or rc1 suffix — 1.10.0b4 is
the fourth beta of 1.10.0, before general availability.

Install the latest pre-release with the tool you use:

$ pip install --user --upgrade --pre tmuxp

$ uv add tmuxp --prerelease allow

$ uvx --from 'tmuxp' --prerelease allow tmuxp

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

After the pipx install, load with tmuxp@next load [session].

Or track trunk directly (it can break):

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

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

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

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

Commands Copy Chapter

:::{seealso}

{ref}examples, {ref}commands, {ref}completion.

:::

tmuxp launches workspaces / sessions from JSON and YAML files.

Workspace files live in $HOME/.tmuxp, or in a project directory as
.tmuxp.yaml, .tmuxp.yml, or .tmuxp.json. Every workspace file needs:

1. a session_name
2. a list of windows
3. a list of panes for every window

Create a file, ~/.tmuxp/example.yaml:

:language: yaml

$ tmuxp load example.yaml

This builds and attaches your session.

Load several at once:

$ tmuxp load example.yaml anothersession.yaml

If you're already inside a session, tmuxp offers to switch-client for you, or
to append the new windows to the session you're in.

You can point tmuxp at a different config directory with the TMUXP_CONFIGDIR
environment variable:

$ TMUXP_CONFIGDIR=$HOME/.tmuxpmoo tmuxp load cpython

Or set it in your ~/.bashrc / ~/.zshrc:

$ export TMUXP_CONFIGDIR=$HOME/.yourconfigdir/tmuxp

You can also import configs from teamocil and tmuxinator.

Pythonics Copy Chapter

:::{seealso}

{ref}libtmux python API documentation <libtmux:api> and {ref}developing.

:::

Under the hood, tmuxp drives tmux through
libtmux — an
object-relational mapper and
abstraction layer over tmux(1)'s commands. Each config concept maps to a
libtmux call:

Cli/Completion Copy Section

(completion)=

(completions)=

(cli-completions)=

Completions

Shell completion teaches your shell to finish tmuxp subcommands and flags when
you press Tab. It's optional, and how you set it up depends on your tmuxp
version — 1.17 and newer use shtab, while 1.1 through 1.16 used click. Pick the
section that matches yours.

tmuxp 1.17+ (experimental) Copy Chapter

See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for tmuxp.

Provisional support for completions in tmuxp 1.17+ are powered by shtab. This must be installed separately, as it's not currently bundled with tmuxp.

$ pip install shtab --user

With a uv project you can add it directly as a development dependency:

$ uv add --dev shtab

Or reach for uvx when you want a pipx-style ephemeral install:

$ uvx shtab --help

:::{tab} bash

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

:::

:::{tab} zsh

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

:::

:::{tab} tcsh

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

:::

tmuxp 1.1 to 1.16 Copy Chapter

See the [click library's documentation on shell completion](https://click.palletsprojects.com/en/8.0.x/shell-completion/) for the most up to date way of connecting completion for tmuxp.

tmuxp 1.1 to 1.16 use click's completion:

:::{tab} Bash

~/.bashrc:

eval "$(_TMUXP_COMPLETE=bash_source tmuxp)"

:::

:::{tab} Zsh

~/.zshrc:

eval "$(_TMUXP_COMPLETE=zsh_source tmuxp)"

:::

Cli/Convert Copy Section

(cli-convert)=

tmuxp convert

Convert workspace configuration files between YAML and JSON formats.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: convert

Basic usage Copy Chapter

```console
$ tmuxp convert /path/to/file.yaml
```

```console
$ tmuxp convert /path/to/file.json
```

tmuxp automatically will prompt to convert .yaml to .json and
.json to .yaml.

Cli/Debug Info Copy Section

(cli-debug-info)=

(tmuxp-debug-info)=

tmuxp debug-info

Collect and display system information useful for debugging tmuxp issues and submitting bug reports.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: debug-info

Example output Copy Chapter

$ tmuxp debug-info
--------------------------
environment:
    system: Linux
    arch: x86_64
...

Cli/Edit Copy Section

(edit-config)=

(cli-edit)=

tmuxp edit

Open a workspace configuration file in your default editor for quick modifications.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: edit

Cli/Exit Codes Copy Section

(cli-exit-codes)=

Exit Codes

tmuxp uses standard exit codes for scripting and automation.

Usage in scripts Copy Chapter

Because the exit code is meaningful, a script can check it and react. Test it
explicitly with $?:

#!/bin/bash
tmuxp load my-workspace.yaml
if [ $? -ne 0 ]; then
    echo "Failed to load workspace"
    exit 1
fi

Or short-circuit with || to handle the failure inline:

#!/bin/bash
tmuxp load -d my-workspace.yaml || {
    echo "tmuxp failed with exit code $?"
    exit 1
}

Cli/Freeze Copy Section

(cli-freeze)=

(cli-freeze-reference)=

tmuxp freeze

Export a running tmux session to a workspace configuration file. This allows you to save the current state of your tmux session for later restoration.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: freeze

Basic usage Copy Chapter

Freeze the current session:

$ tmuxp freeze

Freeze a specific session by name:

$ tmuxp freeze [session_name]

Overwrite an existing workspace file:

$ tmuxp freeze --force [session_name]

Output format Copy Chapter

tmuxp will offer to save your session state to .json or .yaml.

If no session is specified, it will default to the attached session.

If the --force argument is passed, it will overwrite any existing workspace file with the same name.

Cli/Import Copy Section

(cli-import)=

tmuxp import

Import and convert workspace configurations from other tmux session managers like
teamocil and tmuxinator.

(import-teamocil)=

From teamocil Copy Chapter

Import teamocil configuration files and convert them to tmuxp format.

Command Copy Section

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: import teamocil

Basic usage Copy Section

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

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

(import-tmuxinator)=

From tmuxinator Copy Chapter

Import tmuxinator configuration files and convert them to tmuxp format.

Command Copy Section

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: import tmuxinator

Basic usage Copy Section

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

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

Cli/Index Copy Section

(cli)=

(commands)=

CLI Reference

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} tmuxp load
:link: load
:link-type: doc
Load tmux sessions from workspace configs.
:::

:::{grid-item-card} tmuxp shell
:link: shell
:link-type: doc
Interactive Python shell with tmux context.
:::

:::{grid-item-card} tmuxp freeze
:link: freeze
:link-type: doc
Export running sessions to config files.
:::

:::{grid-item-card} tmuxp convert
:link: convert
:link-type: doc
Convert between YAML and JSON formats.
:::

:::{grid-item-card} Exit Codes
:link: exit-codes
:link-type: doc
Exit codes for scripting and automation.
:::

:::{grid-item-card} Recipes
:link: recipes
:link-type: doc
Copy-pasteable command invocations.
:::

::::

:caption: General commands
:maxdepth: 1

load
shell
ls
search

:caption: Configuration
:maxdepth: 1

edit
import
convert
freeze

:caption: Diagnostic
:maxdepth: 1

debug-info

:caption: Completion
:maxdepth: 1

completion

:caption: Reference
:maxdepth: 1

exit-codes
recipes

(cli-main)=

(tmuxp-main)=

Main command Copy Chapter

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

Command Copy Section

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :nosubcommands:

    subparser_name : @replace
        See :ref:`cli-ls`

Cli/Load Copy Section

(cli-load)=

(tmuxp-load)=

(tmuxp-load-reference)=

tmuxp load

Load a tmux session from a workspace file — this is the command you reach for
most. Point it at a project directory or a YAML/JSON file and tmuxp builds the
session and attaches you to it; the flags below are for the cases where you want
something other than that default.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: load

Basic usage Copy Chapter

You can load your tmuxp file and attach the tmux session via a few
shorthands:

1. The directory with a .tmuxp.{yaml,yml,json} file in it
2. The name of the project file in your $HOME/.tmuxp folder
3. The direct path of the tmuxp file you want to load

Path to folder with .tmuxp.yaml, .tmuxp.yml, .tmuxp.json:

Projects with a file named `.tmuxp.yaml` or `.tmuxp.json` can be loaded:

```console
// current directory
$ tmuxp load .
```

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

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

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

Name of the config, assume `$HOME/.tmuxp/myconfig.yaml`:

```console
$ tmuxp load myconfig
```

Direct path to json/yaml file:

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

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

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

Absolute and relative directory paths are supported.

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

Inside sessions Copy Chapter

When you load a workspace from inside an existing tmux client, tmuxp asks what
you want rather than guessing — switch to the freshly built session, append its
windows to the session you're in, or build it detached and stay put:

Already inside TMUX, switch to session? yes/no
Or (a)ppend windows in the current active session?
[y/n/a]:

:::{mermaid}
:caption: Loading from inside an existing tmux client.
:alt: tmuxp load prompt choices inside an existing tmux client
:name: tmuxp-load-inside-client
:responsive: fit

flowchart TD
load["tmuxp load"]:::cmd --> q{"y / n / a ?"}
q -->|yes| switch["build the new session, switch the client to it"]
q -->|a| append["append its windows to the current session"]
q -->|no| detached["build it detached, stay where you are"]
:::

Options Copy Chapter

All of these options can be preselected to skip the prompt:

• Attach / open the client after load:

  console Copy

  $ tmuxp load -y config

• Detached / open in background:

  console Copy

  $ tmuxp load -d config

• Append windows to existing session

  console Copy

  $ tmuxp load -a config

Loading multiple sessions Copy Chapter

Multiple sessions can be loaded at once. The first ones will be created
without being attached. The last one will be attached if there is no
-d flag on the command line.

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

Custom session name Copy Chapter

A session name can be provided at the terminal. If multiple sessions
are created, the last session is named from the terminal.

$ tmuxp load -s [new_session_name] [filename1] ...

Logging Copy Chapter

The output of the load command can be logged to a file for
debugging purposes. the log level can be controlled with the global
--log-level option (defaults to INFO).

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

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

Progress display Copy Chapter

When loading a workspace, tmuxp shows an animated spinner with build progress. The spinner updates as windows and panes are created, giving real-time feedback during session builds.

Presets Copy Section

Five built-in presets control the spinner format:

Select a preset with --progress-format:

$ tmuxp load --progress-format minimal myproject

Or via environment variable:

$ TMUXP_PROGRESS_FORMAT=verbose tmuxp load myproject

Custom format tokens Copy Section

Use a custom format string with any of the available tokens:

Example:

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

Panel lines Copy Section

The spinner shows script output in a panel below the spinner line. Control the panel height with --progress-lines:

Hide the panel entirely (script output goes to stdout):

$ tmuxp load --progress-lines 0 myproject

Show unlimited lines (capped to terminal height):

$ tmuxp load --progress-lines -1 myproject

Set a custom height (default is 3):

$ tmuxp load --progress-lines 5 myproject

Disabling progress Copy Section

Disable the animated spinner entirely:

$ tmuxp load --no-progress myproject

Or via environment variable:

$ TMUXP_PROGRESS=0 tmuxp load myproject

When progress is disabled, logging flows normally to the terminal and no spinner is rendered.

Before-script behavior Copy Section

During before_script execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.

Cli/Ls Copy Section

(cli-ls)=

(ls-config)=

tmuxp ls

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

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: ls

Cli/Recipes Copy Section

(cli-recipes)=

Recipes

Copy-pasteable command invocations for common tasks. Each command has a full
reference — with every flag — under {ref}cli.

Load a workspace Copy Chapter

$ tmuxp load my-workspace.yaml

Load in detached mode Copy Chapter

$ tmuxp load -d my-workspace.yaml

Load from a project directory Copy Chapter

$ tmuxp load .

Freeze a running session Copy Chapter

$ tmuxp freeze my-session

Convert YAML to JSON Copy Chapter

$ tmuxp convert my-workspace.yaml

Convert JSON to YAML Copy Chapter

$ tmuxp convert my-workspace.json

List available workspaces Copy Chapter

$ tmuxp ls

Search workspaces Copy Chapter

$ tmuxp search my-project

Edit a workspace config Copy Chapter

$ tmuxp edit my-workspace

Collect debug info Copy Chapter

$ tmuxp debug-info

Shell with tmux context Copy Chapter

$ tmuxp shell

Access libtmux objects directly:

$ tmuxp shell --best --command 'print(server.sessions)'

Cli/Search Copy Section

(cli-search)=

(search-config)=

tmuxp search

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

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: search

Cli/Shell Copy Section

(cli-shell)=

(tmuxp-shell)=

tmuxp shell

Launch an interactive Python shell with libtmux objects pre-loaded. Like
Django's shell command, it hands you the current tmux server, sessions,
windows, and panes already wired up, so you can poke at a live session or
prototype a script without writing boilerplate.

Command Copy Chapter

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: shell

Interactive usage Copy Chapter

Run tmuxp shell to drop into a Python console with the current tmux
{class}server <libtmux.Server>, {class}session <libtmux.Session>,
{class}window <libtmux.Window>, and {class}pane <libtmux.Pane> already bound.
Pass arguments to select a specific one:

(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)))

Running code directly Copy Chapter

Pass -c to run a snippet and exit, much like python -c:

$ tmuxp shell -c 'python code'

:width: 878
:height: 109
:loading: lazy

The same objects are in scope. Name a server, then a window, to narrow what the
snippet sees:

$ tmuxp shell -c 'print(session.name); print(window.name)'
my_server
my_window

$ tmuxp shell my_server my_window -c 'print(window.name.upper())'
MY_WINDOW

Inside a tmux pane — or attached to the default server — the pane is in scope
too:

$ tmuxp shell -c 'print(pane.id); print(pane.window.name)'
%2
my_window

Debugger integration Copy Chapter

tmuxp shell supports PEP 553's PYTHONBREAKPOINT and compatible
debuggers, such as ipdb:

$ pip install --user ipdb

Inside a uv-managed
project, add ipdb as a development dependency:

$ uv add --dev ipdb

For a pipx-style ad hoc install, run it through uvx:

$ uvx --from ipdb ipdb3 --help

$ env PYTHONBREAKPOINT=ipdb.set_trace tmuxp shell

Shell detection Copy Chapter

tmuxp shell drops into the richest shell available in your site packages. Pick
one yourself with a flag:

• --pdb: plain {func}breakpoint (python 3.7+) or {func}pdb.set_trace
• --code: drop into {func}code.interact, accepts --use-pythonrc
• --bpython: drop into bpython
• --ipython: drop into IPython
• --ptpython: drop into ptpython, accepts --use-vi-mode
• --ptipython: drop into IPython + ptpython, accepts --use-vi-mode

Configuration/Environmental Variables Copy Section

(environmental-variables)=

Environmental variables

These environment variables tune how tmuxp finds your workspaces and how much it
shows you while loading — set from your shell, outside any workspace file. You
rarely need them: tmuxp works out of the box. Reach for one when you want to
point tmuxp at a different config directory, quiet or reshape the load progress
display, or work around a rare tmux quirk. The progress variables each mirror a
{ref}tmuxp load <cli-load> flag, noted alongside the variable.

(TMUXP_CONFIGDIR)=

`TMUXP_CONFIGDIR` Copy Chapter

Example: TMUXP_CONFIGDIR=$HOME/.mytmuxpconfigdir tmuxp load cpython

(LIBTMUX_TMUX_FORMAT_SEPARATOR)=

`LIBTMUX_TMUX_FORMAT_SEPARATOR` Copy Chapter

:::{seealso}

{ref}LIBTMUX_TMUX_FORMAT_SEPARATOR <libtmux:libtmux_tmux_format_separator>
in the libtmux API.

:::

In rare circumstances the tmux -F separator under the hood may cause issues
building sessions. For this case you can override it here.

$ env LIBTMUX_TMUX_FORMAT_SEPARATOR='__SEP__' tmuxp load [session]

(TMUXP_PROGRESS)=

`TMUXP_PROGRESS` Copy Chapter

Master on/off switch for the animated progress spinner during tmuxp load.
Defaults to 1 (enabled). Set to 0 to disable:

$ TMUXP_PROGRESS=0 tmuxp load myproject

Equivalent to the --no-progress CLI flag.

(TMUXP_PROGRESS_FORMAT)=

`TMUXP_PROGRESS_FORMAT` Copy Chapter

Set the spinner line format. Accepts a preset name (default, minimal, window, pane, verbose) or a custom format string with tokens like {session}, {bar}, {progress}:

$ TMUXP_PROGRESS_FORMAT=minimal tmuxp load myproject

Custom format example:

$ TMUXP_PROGRESS_FORMAT="{session} {bar} {overall_percent}%" tmuxp load myproject

Equivalent to the --progress-format CLI flag.

(TMUXP_PROGRESS_LINES)=

`TMUXP_PROGRESS_LINES` Copy Chapter

Number of script-output lines shown in the spinner panel. Defaults to 3.

Set to 0 to hide the panel entirely (script output goes to stdout):

$ TMUXP_PROGRESS_LINES=0 tmuxp load myproject

Set to -1 for unlimited lines (capped to terminal height):

$ TMUXP_PROGRESS_LINES=-1 tmuxp load myproject

Equivalent to the --progress-lines CLI flag.

Configuration/Examples Copy Section

(examples)=

Examples

This is a gallery of working workspace files — each a small, complete YAML (with
its JSON twin) you can copy, load, and adapt. They run from the simplest
two-pane split up to a full development environment, and many preview the panes
they build. Skim for the feature you need — inline shorthand, blank panes,
environment variables, pane shells, focus, history, timed pauses — and lift the
snippet.

Short hand / inline style Copy Chapter

tmuxp has a short-hand syntax for those who like to keep a workspace concise.

:::{tmux-layout}
:size: 36x12
:layout: even-vertical

echo 'did you know' echo 'you can inline' Copy Chapter

echo 'single commands' Copy Chapter

echo 'for panes'
:::

```{literalinclude} ../../examples/shorthands.yaml
:language: yaml

```

```{literalinclude} ../../examples/shorthands.json
:language: json

```

Blank panes Copy Chapter

No need to repeat pwd or a dummy command. A null, 'blank',
'pane' are valid.

Note '' counts as an empty carriage return.

```{literalinclude} ../../examples/blank-panes.yaml
:language: yaml

```

```{literalinclude} ../../examples/blank-panes.json
:language: json

```

2 panes Copy Chapter

:::{tmux-layout}
:size: 30x10
:layout: even-vertical

echo hello Copy Chapter

echo hello
:::

```{literalinclude} ../../examples/2-pane-vertical.yaml
:language: yaml

```

```{literalinclude} ../../examples/2-pane-vertical.json
:language: json

```

3 panes Copy Chapter

:::{tmux-layout}
:size: 44x12
:layout: main-horizontal

cd /var/log ls -al | grep \.log Copy Chapter

echo hello Copy Chapter

echo hello
:::

```{literalinclude} ../../examples/3-pane.yaml
:language: yaml

```

```{literalinclude} ../../examples/3-pane.json
:language: json

```

4 panes Copy Chapter

:::{tmux-layout}
:size: 44x12
:layout: tiled

cd /var/log ls -al | grep \.log Copy Chapter

echo hello Copy Chapter

echo hello Copy Chapter

echo hello
:::

```{literalinclude} ../../examples/4-pane.yaml
:language: yaml

```

```{literalinclude} ../../examples/4-pane.json
:language: json

```

Start Directory Copy Chapter

Equivalent to tmux new-window -c <start-directory>.

```{literalinclude} ../../examples/start-directory.yaml
:language: yaml

```

```{literalinclude} ../../examples/start-directory.json
:language: json

```

Environment variable replacing Copy Chapter

tmuxp will replace environment variables wrapped in curly brackets
for values of these settings:

• start_directory
• before_script
• session_name
• window_name
• shell_command_before
• global_options
• options in session scope and window scope

tmuxp replaces these variables before-hand with variables in the
terminal tmuxp invokes in.

In this case of this example, assuming the username "user":

$ MY_ENV_VAR=foo tmuxp load examples/env-variables.yaml

and your session name will be session - user (foo).

Shell variables in shell_command do not support this type of
concatenation. shell_command and shell_command_before both
support normal shell variables, since they are sent into panes
automatically via send-key in tmux(1). See ls $PWD in
example.

If you have a special case and would like to see behavior changed,
please make a ticket on the issue tracker.

```{literalinclude} ../../examples/env-variables.yaml
:language: yaml

```

```{literalinclude} ../../examples/env-variables.json
:language: json

```

Environment variables Copy Chapter

tmuxp will set session, window and pane environment variables.

Setting environment variables for windows and panes requires tmuxp 1.19 or newer.

```{literalinclude} ../../examples/session-environment.yaml
:language: yaml

```

```{literalinclude} ../../examples/session-environment.json
:language: json

```

Focusing Copy Chapter

tmuxp allows focus: true for assuring windows and panes are attached /
selected upon loading.

```{literalinclude} ../../examples/focus-window-and-panes.yaml
:language: yaml

```

```{literalinclude} ../../examples/focus-window-and-panes.json
:language: json

```

Terminal History Copy Chapter

tmuxp allows suppress_history: false to override the default command /
suppression when building the workspace.
This will add the shell_command to the shell history in the pane.
The suppression of the shell_command commands from the shell's history
occurs by prefixing the commands with a space when suppress_history: true.
Accordingly, this functionality depends on the shell being appropriately
configured: bash requires the shell variable HISTCONTROL to be set and
include either of the values ignorespace or ignoreboth (to also ignore
sequential duplicate commands), and zsh requires setopt HIST_IGNORE_SPACE.

```{literalinclude} ../../examples/suppress-history.yaml
:language: yaml

```

```{literalinclude} ../../examples/suppress-history.json
:language: json

```

(enter)=

Skip command execution Copy Chapter

See more at {ref}enter.

:::{note}

Experimental setting: behavior and api is subject to change until stable.

:::

`enter: false` option. Pane-level support.

Omit sending {kbd}enter to key commands. Equivalent to
{meth}send_keys(enter=False) <libtmux.Pane.send_keys>.

```{literalinclude} ../../examples/skip-send.yaml
:language: yaml

```

```{literalinclude} ../../examples/skip-send.json
:language: json

```

```{literalinclude} ../../examples/skip-send-pane-level.yaml
:language: yaml

```

```{literalinclude} ../../examples/skip-send-pane-level.json
:language: json

```

(sleep)=

Pausing commands Copy Chapter

:::{note}

Experimental setting: behavior and api is subject to change until stable.

:::

`sleep_before` and `sleep_after` options added. Pane and command-level support.

**Blocking.** This will delay loading as it runs synchronously for each pane as
{mod}`asyncio` is not implemented yet.

Omit sending {kbd}enter to key commands. Equivalent to having
a {func}time.sleep before and after {meth}~libtmux.Pane.send_keys.

This is especially useful for expensive commands where the terminal needs some
breathing room (virtualenv, poetry, pipenv, uv, sourcing a configuration,
launching a tui app, etc).

```{literalinclude} ../../examples/sleep-virtualenv.yaml
:language: yaml

```

```{literalinclude} ../../examples/sleep.yaml
:language: yaml

```

```{literalinclude} ../../examples/sleep.json
:language: json

```

```{literalinclude} ../../examples/sleep-pane-level.yaml
:language: yaml

```

```{literalinclude} ../../examples/sleep-pane-level.json
:language: json

```

Window Index Copy Chapter

You can specify a window's index using the window_index property. Windows
without window_index will use the lowest available window index.

```{literalinclude} ../../examples/window-index.yaml
:language: yaml

```

```{literalinclude} ../../examples/window-index.json
:language: json

```

Shell per pane Copy Chapter

Every pane can have its own shell or application started. This allows for usage
of the remain-on-exit setting to be used properly, but also to have
different shells on different panes.

```{literalinclude} ../../examples/pane-shell.yaml
:language: yaml

```

```{literalinclude} ../../examples/pane-shell.json
:language: json

```

Set tmux options Copy Chapter

Works with global (server-wide) options, session options
and window options.

Including automatic-rename, default-shell,
default-command, etc.

```{literalinclude} ../../examples/options.yaml
:language: yaml

```

```{literalinclude} ../../examples/options.json
:language: json

```

Set window options after pane creation Copy Chapter

Apply window options after panes have been created. Useful for
synchronize-panes option after executing individual commands in each
pane during creation.

```{literalinclude} ../../examples/2-pane-synchronized.yaml
:language: yaml

```

```{literalinclude} ../../examples/2-pane-synchronized.json
:language: json

```

Main pane height Copy Chapter

Percentage Copy Section

:::{versionadded} 1.46.0

Before this, tmuxp layouts would not detect the terminal's size.

:::

```{literalinclude} ../../examples/main-pane-height-percentage.yaml
:language: yaml

```

```{literalinclude} ../../examples/main-pane-height-percentage.json
:language: json

```

Rows Copy Section

```{literalinclude} ../../examples/main-pane-height.yaml
:language: yaml

```

```{literalinclude} ../../examples/main-pane-height.json
:language: json

```

Super-advanced dev environment Copy Chapter

:::{seealso}

{ref}tmuxp-developer-config in the {ref}developing section.

:::

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

```

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

```

Multi-line commands Copy Chapter

You can use YAML's multiline syntax to easily split multiple
commands into the same shell command: https://stackoverflow.com/a/21699210

```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
```

Bootstrap project before launch Copy Chapter

You can use before_script to run a script before the tmux session
starts building. This can be used to start a script to create a virtualenv
or download a virtualenv/rbenv/package.json's dependency files before
tmuxp even begins building the session.

It works by using the Exit Status code returned by a script. Your
script can be any type, including bash, python, ruby, etc.

A successful script will exit with a status of 0.

Important: the script file must be chmod executable +x or 755.

Run a python script (and check for its return code), the script is
relative to the .tmuxp.yaml's root (Windows and panes omitted in
this example):

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

```

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

```

Run a shell script + check for return code on an absolute path. (Windows
and panes omitted in this example)

```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"
}

```

Per-project tmuxp workspaces Copy Chapter

You can load your software project in tmux by placing a .tmuxp.yaml or
.tmuxp.json in the project's workspace and loading it.

Use {ref}tmuxp load <cli-load> with an absolute filename, or $ tmuxp load .
when the workspace is in the current directory.

$ tmuxp load ~/workspaces/myproject.yaml

See examples of tmuxp in the wild. Have a project workspace to show off?
Edit this page.

• https://github.com/tony/dockerfiles/blob/master/.tmuxp.yaml
• https://github.com/vcs-python/vcspull/blob/master/.tmuxp.yaml
• https://github.com/tony/sphinxcontrib-github/blob/master/.tmuxp.yaml

You can use start_directory: ./ to make the directories relative to
the workspace file / project root.

Bonus: pipenv auto-bootstrapping Copy Chapter

:::{versionadded} 1.3.4

before_script CWD's into the root (session)-level
start_directory.

:::

If you use pipenv / poetry / uv, you can use a script like this to ensure
your packages are installed:

```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

```

You can also source yourself into the virtual environment using
shell_command_before:

```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

```

Kung fu Copy Chapter

:::{note}

tmuxp sessions can be scripted in python. The first way is to use the
ORM in the {ref}API. The second is to pass a {class}dict into
{class}~tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder with a correct schema.
See: {func}~tmuxp.workspace.validation.validate_schema.

:::

Add yours? Submit a pull request to the github site!

Configuration/Index Copy Section

(config)=

(configuration)=

(workspace)=

Workspace files

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Top-level Options
:link: top-level
:link-type: doc
Session and window configuration keys.
:::

:::{grid-item-card} Environment Variables
:link: environmental-variables
:link-type: doc
TMUXP_CONFIGDIR and other env vars.
:::

:::{grid-item-card} Examples
:link: examples
:link-type: doc
Sample workspace configurations.
:::

:::{grid-item-card} Workspace builders
:link: workspace-builders
:link-type: doc
Select a builder and tune pane readiness.
:::

::::

tmuxp loads your terminal workspace into tmux using workspace files.

The workspace file can be JSON or YAML. Its declarative style resembles tmux's object hierarchy: session, window, and panes.

Launching your session Copy Chapter

Once you have tmuxp installed alongside tmux, you can load a workspace with:

$ tmuxp load ./path/to/file

tmuxp will offer to assist when:

• Session already exists: tmuxp will prompt you to re-attach. It does this
  by checking if the workspace's session_name matches a session already
  running on the same server.
• When inside a tmux client, tmuxp will let you create a new session and switch to it, or append the windows to your existing
  session.

What's in a workspace file? Copy Chapter

1. A session name
2. A list of windows
3. A list of panes for each window
4. A list of commands for each pane

:::{mermaid}
:caption: A workspace file mirrors tmux's own hierarchy.
:alt: tmuxp workspace file hierarchy from session to windows, panes, and shell commands
:name: tmuxp-workspace-hierarchy
:responsive: fit

flowchart TD
session["session_name"]:::cmd --> w1["window"]
session --> w2["window"]
w1 --> p1["pane"]
w1 --> p2["pane"]
p1 --> c1["shell_command"]:::cmd
p1 --> c2["shell_command"]:::cmd
:::

```yaml
session_name: My session
windows:
- window_name: Window 1
  panes:
  - shell_command:
    - cmd: echo "pane 1"
  - shell_command:
    - cmd: echo "pane 2"
```

```{literalinclude} ../../examples/minimal.yaml
:language: yaml

```

As of 1.11.x.

Breaking down the basic workspace into sections:

1. A session name

   yaml Copy

   session_name: My session

2. A list of windows

   yaml Copy

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

3. A list of panes for each window

   yaml Copy

   windows:
     panes:
       -  # pane settings
       -  # pane settings

4. A list of commands for each pane

   yaml Copy

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

Where do I store workspace files? Copy Chapter

Direct Copy Section

You can create a workspace and load it from anywhere in your file system.

$ tmuxp load [workspace-file]

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

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

User-based workspaces Copy Section

tmuxp uses the XDG Base Directory specification.

Often on POSIX machines, you will store them in ~/.config/tmuxp.

Assume you store apple.yaml in $XDG_CONFIG_HOME/tmuxp/apple.yaml, you can
then use:

$ tmuxp load apple

:::{seealso}

This path can be overridden by {ref}TMUXP_CONFIGDIR

:::

Project-specific Copy Section

You can store a workspace in your project's root directory as .tmuxp.yaml or .tmuxp.json, then:

Assume .tmuxp.yaml inside /opt/myapp

$ tmuxp load [workspace-file]

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

```console
$ tmuxp load /opt/myapp
```

Reference and usage Copy Chapter

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Top-level Options
:link: top-level
:link-type: doc
Session and window configuration keys.
:::

:::{grid-item-card} Environment Variables
:link: environmental-variables
:link-type: doc
TMUXP_CONFIGDIR and other env vars.
:::

:::{grid-item-card} Examples
:link: examples
:link-type: doc
Sample workspace configurations.
:::

:::{grid-item-card} Workspace builders
:link: workspace-builders
:link-type: doc
Select a builder and tune pane readiness.
:::

::::

:hidden:

top-level
environmental-variables
examples
workspace-builders

Configuration/Top Level Copy Section

(top-level)=
(top-level-config)=

Top-level configuration

Top-level keys describe the session as a whole — its name, where it starts,
the tmux options it sets — and sit above the windows and panes that fill
it. Only session_name is required; leave the rest out and a workspace with
just a name and a list of windows loads fine. This page covers session_name
and the keys for choosing a workspace builder. For the full set of session,
window, and pane keys, work through {ref}examples.

`session_name` Copy Chapter

The name tmux gives the session — and the name tmuxp checks against when it
decides whether that session is already running. It need not match the
workspace filename.

For example, apple.yaml:

session_name: banana
windows:
  - panes:
      -

Load it detached:

$ tmuxp load ./apple.yaml -d

tmuxp reads apple.yaml from the current directory and builds a tmux session
called banana in the background — -d is detached. Attach to it with tmux
directly:

$ tmux attach -t banana

Workspace builder keys Copy Chapter

A workspace file can also choose a custom builder and tune its behavior with
workspace_builder, workspace_builder_paths, and workspace_builder_options.
Most workspaces never set these — leave them out and you get tmuxp's built-in
classic builder.

{ref}`workspace-builders`

Configuration/Workspace Builders Copy Section

(workspace-builders)=

Workspace builders

A workspace builder is the part of tmuxp that turns a workspace configuration into a
live tmux session — it creates the session, lays out its windows and panes, and runs
their commands. You usually never have to think about it: tmuxp ships with the
built-in
{class}classic builder <tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder>,
and your YAML or JSON workspace files load through it out of the box, just as
they always have. Everything on this page is optional; leave a setting out to
fall back to the default.

:::{mermaid}
:caption: How a workspace file becomes a live tmux session.
:alt: tmuxp load reading workspace config through a workspace builder to attach a session
:name: tmuxp-workspace-builder-flow
:responsive: fit

config:
flowchart:
wrappingWidth: 500

flowchart TD
load["tmuxp load <workspace-file>"]:::cmd -->|reads workspace config| builder["Workspace Builder"]
builder -->|"creates session, windows, panes"| attach["Attach tmux session"]
:::

Workspaces with special needs can reach for a builder's options to fine-tune how a
session loads. The classic builder, for instance, can wait for a pane's shell prompt
before sending its layout and commands — by default only when that shell is zsh (the
pane_readiness option). Waiting makes a session a little slower to load, but
guarantees the workspace is fully prepped before you attach.

You can also send a workspace through a different or custom builder instead of
the classic one, and tune its options the same way. For the braver cases, you
can subclass the
{class}classic builder <tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder>
or write your own in Python on top of
libtmux — see
{ref}custom-workspace-builders for writing, packaging, testing, and the trust
boundary that comes with running builder code.

(workspace-builder-key)=

`workspace_builder` Copy Chapter

This is where you name the builder. Leave it out — or set classic — and you get
tmuxp's built-in builder, with nothing imported. When you name something else, tmuxp
works out what you mean from the shape of the value, in this order:

1. absent or empty → the built-in classic builder (nothing is imported);
2. contains : → a module:attr object reference;
3. no . and no : → a builder registered under the tmuxp.workspace_builders
   entry-point group, selected by name;
4. dotted with no : → an entry-point name if one is registered, otherwise a
   module.attr import path.

session_name: my-session
workspace_builder: classic
windows:
  - panes:
      - vim

See {ref}custom-workspace-builders for selecting and packaging builders, and
{func}~tmuxp.workspace.builder.registry.resolve_builder_class for the resolver.

(workspace-builder-paths-key)=

`workspace_builder_paths` Copy Chapter

When your builder lives outside tmuxp's environment — say, a script sitting in your
config directory — this tells tmuxp where to find it. Give it a single directory or a
list of them. tmuxp expands ~ and environment variables, reads relative entries
against the workspace file's own directory, and expects each one to be a directory
that already exists. The paths join {data}sys.path only for the import and
build, not for the rest of your session.

workspace_builder: my_local_builder:CustomBuilder
workspace_builder_paths:
  - ~/.config/tmuxp/builders

A workspace file that names a builder runs that builder's Python code. Only load
workspace files you trust. See the security note in {ref}`custom-workspace-builders`.

(workspace-builder-options-key)=

`workspace_builder_options` Copy Chapter

This holds builder-behavior settings, whichever builder you use. For now there's just
one, pane_readiness, which decides whether tmuxp waits for a pane's shell prompt
before it sends that pane's layout and commands — a guard against a zsh prompt-redraw
artifact:

workspace_builder_options:
  pane_readiness: auto

pane_readiness also accepts truthy/falsy aliases — true/on/yes/1 map to
always, and false/off/no/0 map to never (full list in
{ref}custom-workspace-builders). An unrecognized value fails the load with:

invalid pane_readiness value: 'sometimes'; expected one of: auto, always/true/on/yes/1, never/false/off/no/0

A pane that runs a custom shell or window_shell never waits, whatever you set here.
See {class}~tmuxp.workspace.options.PaneReadiness and
{class}~tmuxp.workspace.options.WorkspaceBuilderOptions for the parsing rules.

Minimal complete example Copy Chapter

```yaml
session_name: my-session
workspace_builder: classic
workspace_builder_paths:
  - ~/.config/tmuxp/builders
workspace_builder_options:
  pane_readiness: auto
windows:
  - window_name: editor
    panes:
      - vim
```

```json
{
  "session_name": "my-session",
  "workspace_builder": "classic",
  "workspace_builder_paths": ["~/.config/tmuxp/builders"],
  "workspace_builder_options": {
    "pane_readiness": "auto"
  },
  "windows": [
    {
      "window_name": "editor",
      "panes": ["vim"]
    }
  ]
}
```

{ref}`custom-workspace-builders` — narrative guide to selecting, packaging,
writing, and testing builders ·
{class}`~tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder` ·
{class}`~tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol`

Internals/Api/Cli/Convert Copy Section

tmuxp convert - `tmuxp.cli.convert`

.. automodule:: tmuxp.cli.convert
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Debug Info Copy Section

tmuxp debug-info - `tmuxp.cli.debug_info`

.. automodule:: tmuxp.cli.debug_info
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Edit Copy Section

tmuxp edit - `tmuxp.cli.edit`

.. automodule:: tmuxp.cli.edit
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Formatter Copy Section

tmuxp formatter - `tmuxp.cli._formatter`

.. automodule:: tmuxp.cli._formatter
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Freeze Copy Section

tmuxp freeze - `tmuxp.cli.freeze`

.. automodule:: tmuxp.cli.freeze
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Import Config Copy Section

tmuxp import - `tmuxp.cli.import_config`

.. automodule:: tmuxp.cli.import_config
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Index Copy Section

(api_cli)=

CLI

:::{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.
:::

convert
debug_info
edit
freeze
formatter
import_config
load
ls
progress
search
shell
utils

`tmuxp.cli` Copy Chapter

.. automodule:: tmuxp.cli
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Load Copy Section

tmuxp load - `tmuxp.cli.load`

.. automodule:: tmuxp.cli.load
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Ls Copy Section

tmuxp ls - `tmuxp.cli.ls`

.. automodule:: tmuxp.cli.ls
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Progress Copy Section

tmuxp progress - `tmuxp.cli._progress`

.. automodule:: tmuxp.cli._progress
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Search Copy Section

tmuxp search - `tmuxp.cli.search`

.. automodule:: tmuxp.cli.search
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Shell Copy Section

tmuxp shell - `tmuxp.cli.shell`

.. automodule:: tmuxp.cli.shell
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Cli/Utils Copy Section

CLI utilities - `tmuxp.cli.utils`

.. automodule:: tmuxp.cli.utils
   :members:
   :exclude-members: ColorMode
   :show-inheritance:
   :undoc-members:

Internals/Api/ Internal/Colors Copy Section

Colors - `tmuxp._internal.colors`

:::{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.
:::

.. automodule:: tmuxp._internal.colors
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/ Internal/Config Reader Copy Section

Config reader - `tmuxp._internal.config_reader`

:::{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.
:::

.. automodule:: tmuxp._internal.config_reader
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/ Internal/Index Copy Section

(api-internal)=

Internal Modules

:::{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.
:::

colors
config_reader
private_path
types

Internals/Api/ Internal/Private Path Copy Section

Private path - `tmuxp._internal.private_path`

:::{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.
:::

.. automodule:: tmuxp._internal.private_path
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/ Internal/Types Copy Section

Typings - `tmuxp._internal.types`

.. automodule:: tmuxp._internal.types
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Builder/Classic Copy Section

Classic builder - `tmuxp.workspace.builder.classic`

.. automodule:: tmuxp.workspace.builder.classic
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Builder/Index Copy Section

Builder - `tmuxp.workspace.builder`

.. py:module:: tmuxp.workspace.builder

tmuxp.workspace.builder is a package. The classic, default builder lives in
{mod}tmuxp.workspace.builder.classic; the public contract and the selection
machinery live alongside it.

{class}WorkspaceBuilder <tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder>
remains importable from {mod}tmuxp.workspace.builder as a backwards-compatible
alias of {class}~tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder.

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Classic builder
:link: classic
:link-type: doc
The built-in, default builder — tmuxp.workspace.builder.classic.
:::

:::{grid-item-card} Builder protocol
:link: protocol
:link-type: doc
The contract a builder must satisfy — tmuxp.workspace.builder.protocol.
:::

:::{grid-item-card} Builder registry
:link: registry
:link-type: doc
Builder selection and trusted import paths — tmuxp.workspace.builder.registry.
:::

::::

:hidden:

classic
protocol
registry

Internals/Api/Workspace/Builder/Protocol Copy Section

Builder protocol - `tmuxp.workspace.builder.protocol`

.. automodule:: tmuxp.workspace.builder.protocol
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Builder/Registry Copy Section

Builder registry - `tmuxp.workspace.builder.registry`

.. automodule:: tmuxp.workspace.builder.registry
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Constants Copy Section

Constants - `tmuxp.workspace.constants`

.. automodule:: tmuxp.workspace.constants
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Finders Copy Section

Finders - `tmuxp.workspace.finders`

.. automodule:: tmuxp.workspace.finders
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Freezer Copy Section

Freezer - `tmuxp.workspace.freezer`

.. automodule:: tmuxp.workspace.freezer
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Importers Copy Section

Importers - `tmuxp.workspace.importers`

.. automodule:: tmuxp.workspace.importers
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Index Copy Section

(workspace)=

Workspace

:::{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.
:::

builder/index
constants
finders
freezer
importers
loader
options
validation

Internals/Api/Workspace/Loader Copy Section

Loader - `tmuxp.workspace.loader`

.. automodule:: tmuxp.workspace.loader
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Options Copy Section

Options - `tmuxp.workspace.options`

.. automodule:: tmuxp.workspace.options
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Workspace/Validation Copy Section

Validation - `tmuxp.workspace.validation`

.. automodule:: tmuxp.workspace.validation
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Exc Copy Section

Exceptions - `tmuxp.exc`

.. automodule:: tmuxp.exc
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Index Copy Section

(api)=

API Reference

This is the internal Python API — the modules tmuxp's CLI is built from,
documented for contributors and plugin authors. Everyday use goes through the
{ref}CLI <cli>; to drive tmux from Python directly, reach for
libtmux instead.

:::{seealso}
See {ref}libtmux's API <libtmux:api> and {ref}Quickstart <libtmux:quickstart> to see how you can control
tmux via python API calls.
:::

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Workspace
:link: workspace/index
:link-type: doc
Finding, loading, building, and freezing sessions.
:::

:::{grid-item-card} CLI modules
:link: cli/index
:link-type: doc
The {mod}argparse commands behind each subcommand.
:::

:::{grid-item-card} Plugin API
:link: plugin
:link-type: doc
The {class}~tmuxp.plugin.TmuxpPlugin base class and its hooks.
:::

:::{grid-item-card} Internal helpers
:link: _internal/index
:link-type: doc
Config reader, colors, and private path helpers.
:::

:::{grid-item-card} Exceptions
:link: exc
:link-type: doc
The {exc}~tmuxp.exc.TmuxpException hierarchy.
:::

:::{grid-item-card} Logging
:link: log
:link-type: doc
Loggers and user-facing echo helpers.
:::

:::{grid-item-card} Shell
:link: shell
:link-type: doc
Internals of the interactive shell launcher.
:::

:::{grid-item-card} Utilities
:link: util
:link-type: doc
Assorted helpers used across tmuxp.
:::

:::{grid-item-card} Types
:link: types
:link-type: doc
Shared type definitions.
:::

::::

:hidden:

_internal/index
cli/index
workspace/index
exc
log
plugin
shell
util
types

Internals/Api/Log Copy Section

Logging - `tmuxp.log`

.. automodule:: tmuxp.log
   :members:
   :show-inheritance:
   :undoc-members:

Internals/Api/Plugin Copy Section

Plugin - `tmuxp.plugin`

.. automodule:: tmuxp.plugin
   :members:
   :show-inheritance:
   :undoc-members: