(config)=

(configuration)=

(workspace)=

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

::::

tmuxp loads your terminal workspace into tmux using workspace files.

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

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.

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

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

   session_name: My session

2. A list of windows

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

3. A list of panes for each window

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

4. A list of commands for each pane

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

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

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

:::

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

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

::::

:hidden:

top-level
environmental-variables
examples