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#