Workspace files

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.

Launching your session

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

$ tmuxp load ./path/to/file

tmuxp will offers 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

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