Workspace files

Top-level Options

Session and window configuration keys.

Top-level configuration
Environment Variables

TMUXP_CONFIGDIR and other env vars.

Environmental variables
Examples

Sample workspace configurations.

Examples
Workspace builders

Select a builder and tune pane readiness.

Workspace builders

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

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?

  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

A workspace file mirrors tmux's own hierarchy.
session_name: My session
windows:
- window_name: Window 1
  panes:
  - shell_command:
    - cmd: echo "pane 1"
  - shell_command:
    - cmd: echo "pane 2"

session_name: My tmux session
windows:
  - panes:
      -

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

Where do I store workspace files?

Direct

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

$ tmuxp load [workspace-file]

$ tmuxp load ./favorites.yaml

$ tmuxp load /opt/myapp/favorites.yaml

User-based workspaces

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

See also

This path can be overridden by TMUXP_CONFIGDIR

Project-specific

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]

$ tmuxp load ./

$ tmuxp load /opt/myapp

Reference and usage

Top-level Options

Session and window configuration keys.

Top-level configuration
Environment Variables

TMUXP_CONFIGDIR and other env vars.

Environmental variables
Examples

Sample workspace configurations.

Examples
Workspace builders

Select a builder and tune pane readiness.

Workspace builders