tmux workspace manager, forged in TypeScript.

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

Try a preset

Preset

session_name: shorthands
windows:
  - window_name: long form
    panes:
      - shell_command:
          - echo 'did you know'
          - echo 'you can inline'
      - shell_command: echo 'single commands'
      - echo 'for panes'

{
  "session_name": "shorthands",
  "windows": [
    {
      "window_name": "long form",
      "panes": [
        {
          "shell_command": [
            "echo 'did you know'",
            "echo 'you can inline'"
          ]
        },
        {
          "shell_command": "echo 'single commands'"
        },
        "echo 'for panes'"
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: 2-pane-vertical
windows:
  - window_name: my test window
    panes:
      - echo hello
      - echo hello

{
  "session_name": "2-pane-vertical",
  "windows": [
    {
      "window_name": "my test window",
      "panes": [
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: 3-panes
windows:
  - window_name: dev window
    layout: main-vertical
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello

{
  "session_name": "3-panes",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "main-vertical",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

layout main-vertical

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello
      - echo hello

{
  "session_name": "4-pane-split",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "tiled",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

layout tiled

session_name: main-pane-height
start_directory: "~"
windows:
  - layout: main-horizontal
    options:
      main-pane-height: 30
    panes:
      - shell_command:
          - top
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"
    window_name: my window name

{
  "session_name": "main-pane-height",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": 30
      },
      "panes": [
        {
          "shell_command": [
            "top"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ],
      "window_name": "my window name"
    }
  ]
}

layout main-horizontal

session_name: Environment variables test
environment:
  EDITOR: /usr/bin/vim
  DJANGO_SETTINGS_MODULE: my_app.settings.local
  SERVER_PORT: "8009"
windows:
  - window_name: Django project
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
  - window_name: Another Django project
    environment:
      DJANGO_SETTINGS_MODULE: my_app.settings.local
      SERVER_PORT: "8010"
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
      - environment:
          DJANGO_SETTINGS_MODULE: my_app.settings.local-testing
          SERVER_PORT: "8011"
        shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT}

{
  "session_name": "Environment variables test",
  "environment": {
    "EDITOR": "/usr/bin/vim",
    "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
    "SERVER_PORT": "8009"
  },
  "windows": [
    {
      "window_name": "Django project",
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
      ]
    },
    {
      "window_name": "Another Django project",
      "environment": {
        "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
        "SERVER_PORT": "8010"
      },
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}",
        {
          "environment": {
            "DJANGO_SETTINGS_MODULE": "my_app.settings.local-testing",
            "SERVER_PORT": "8011"
          },
          "shell_command": "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: start directory
start_directory: /var/
windows:
  - window_name: should be /var/
    panes:
      - shell_command:
          - echo "\033c
          - it trickles down from session-level"
      - echo hello
  - window_name: should be /var/log
    start_directory: log
    panes:
      - shell_command:
          - echo '\033c
          - window start_directory concatenates to session start_directory
          - if it is not absolute'
      - echo hello
  - window_name: should be ~
    start_directory: "~"
    panes:
      - shell_command:
          - 'echo \\033c ~ has precedence. note: remember to quote ~ in YAML'
      - echo hello
  - window_name: should be /bin
    start_directory: /bin
    panes:
      - echo '\033c absolute paths also have precedence.'
      - echo hello
  - window_name: should be workspace file's dir

    start_directory: ./
    panes:
      - shell_command:
          - echo '\033c
          - ./ is relative to workspace file location
          - ../ will be parent of workspace file
          - ./test will be \"test\" dir inside dir of workspace file'
      - shell_command:
          - echo '\033c
          - This way you can load up workspaces from projects and maintain
          - relative paths.'

{
  "session_name": "start directory",
  "start_directory": "/var/",
  "windows": [
    {
      "window_name": "should be /var/",
      "panes": [
        {
          "shell_command": [
            "echo \"\\033c",
            "it trickles down from session-level\""
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be /var/log",
      "start_directory": "log",
      "panes": [
        {
          "shell_command": [
            "echo '\\033c",
            "window start_directory concatenates to session start_directory",
            "if it is not absolute'"
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be ~",
      "start_directory": "~",
      "panes": [
        {
          "shell_command": [
            "echo \\\\033c ~ has precedence. note: remember to quote ~ in YAML"
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be /bin",
      "start_directory": "/bin",
      "panes": [
        "echo '\\033c absolute paths also have precedence.'",
        "echo hello"
      ]
    },
    {
      "window_name": "should be workspace file's dir",
      "start_directory": "./",
      "panes": [
        {
          "shell_command": [
            "echo '\\033c",
            "./ is relative to workspace file location",
            "../ will be parent of workspace file",
            "./test will be \\\"test\\\" dir inside dir of workspace file'"
          ]
        },
        {
          "shell_command": [
            "echo '\\033c",
            "This way you can load up workspaces from projects and maintain",
            "relative paths.'"
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: 2-pane-synchronized
windows:
  - window_name: Two synchronized panes
    panes:
      - ssh server1
      - ssh server2
    options_after:
      synchronize-panes: on

{
  "session_name": "2-pane-synchronized",
  "windows": [
    {
      "window_name": "Two synchronized panes",
      "panes": [
        "ssh server1",
        "ssh server2"
      ],
      "options_after": {
        "synchronize-panes": "on"
      }
    }
  ]
}

no layout set, so the port tiles the panes

session_name: Blank pane test
windows:
  # Emptiness will simply open a blank pane, if no shell_command_before.
  # All these are equivalent
  - window_name: Blank pane test
    panes:
      -
      - pane
      - blank
  - window_name: More blank panes
    panes:
      - null
      - shell_command:
      - shell_command:
          -
  # an empty string will be treated as a carriage return
  - window_name: Empty string (return)
    panes:
      - ""
      - shell_command: ""
      - shell_command:
          - ""
  # a pane can have other options but still be blank
  - window_name: Blank with options
    panes:
      - focus: true
      - start_directory: /tmp

{
  "session_name": "Blank pane test",
  "windows": [
    {
      "window_name": "Blank pane test",
      "panes": [
        null,
        "pane",
        "blank"
      ]
    },
    {
      "window_name": "More blank panes",
      "panes": [
        null,
        {
          "shell_command": null
        },
        {
          "shell_command": [
            null
          ]
        }
      ]
    },
    {
      "window_name": "Empty string (return)",
      "panes": [
        "",
        {
          "shell_command": ""
        },
        {
          "shell_command": [
            ""
          ]
        }
      ]
    },
    {
      "window_name": "Blank with options",
      "panes": [
        {
          "focus": true
        },
        {
          "start_directory": "/tmp"
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

start_directory: "${PWD}/test"
shell_command_before: "echo ${PWD}"
before_script: "${MY_ENV_VAR}/test3.sh"
session_name: session - ${USER} (${MY_ENV_VAR})
windows:
  - window_name: editor
    panes:
      - shell_command:
          - tail -F /var/log/syslog
    start_directory: /var/log
  - window_name: logging for ${USER}
    options:
      automatic-rename: true
    panes:
      - shell_command:
          - htop
          - ls $PWD

{
  "start_directory": "${PWD}/test",
  "shell_command_before": "echo ${PWD}",
  "before_script": "${MY_ENV_VAR}/test3.sh",
  "session_name": "session - ${USER} (${MY_ENV_VAR})",
  "windows": [
    {
      "window_name": "editor",
      "panes": [
        {
          "shell_command": [
            "tail -F /var/log/syslog"
          ]
        }
      ],
      "start_directory": "/var/log"
    },
    {
      "window_name": "logging for ${USER}",
      "options": {
        "automatic-rename": true
      },
      "panes": [
        {
          "shell_command": [
            "htop",
            "ls $PWD"
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: focus
windows:
  - window_name: attached window
    focus: true
    panes:
      - shell_command:
          - echo hello
          - echo 'this pane should be selected on load'
        focus: true
      - shell_command:
          - cd /var/log
          - echo hello
  - window_name: second window
    shell_command_before: cd /var/log
    panes:
      - pane
      - shell_command:
          - echo 'this pane should be focused, when window switched to first time'
        focus: true
      - pane

{
  "session_name": "focus",
  "windows": [
    {
      "window_name": "attached window",
      "focus": true,
      "panes": [
        {
          "shell_command": [
            "echo hello",
            "echo 'this pane should be selected on load'"
          ],
          "focus": true
        },
        {
          "shell_command": [
            "cd /var/log",
            "echo hello"
          ]
        }
      ]
    },
    {
      "window_name": "second window",
      "shell_command_before": "cd /var/log",
      "panes": [
        "pane",
        {
          "shell_command": [
            "echo 'this pane should be focused, when window switched to first time'"
          ],
          "focus": true
        },
        "pane"
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: main-pane-height
start_directory: "~"
windows:
  - layout: main-horizontal
    options:
      main-pane-height: 67%
    panes:
      - shell_command:
          - top
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"
    window_name: my window name

{
  "session_name": "main-pane-height",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": "67%"
      },
      "panes": [
        {
          "shell_command": [
            "top"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ],
      "window_name": "my window name"
    }
  ]
}

layout main-horizontal

session_name: My tmux session
windows:
  - panes:
      -

{
  "session_name": "My tmux session",
  "windows": [
    {
      "panes": [
        null
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: test window options
start_directory: "~"
global_options:
  default-shell: /bin/sh
  default-command: /bin/sh
options:
  main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variables
windows:
  - layout: main-horizontal
    options:
      automatic-rename: on
    panes:
      - shell_command:
          - man echo
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"

{
  "session_name": "test window options",
  "start_directory": "~",
  "global_options": {
    "default-shell": "/bin/sh",
    "default-command": "/bin/sh"
  },
  "options": {
    "main-pane-height": "${MAIN_PANE_HEIGHT}"
  },
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "automatic-rename": "on"
      },
      "panes": [
        {
          "shell_command": [
            "man echo"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ]
    }
  ]
}

layout main-horizontal

session_name: Pane shell example
windows:
  - window_name: first
    window_shell: /usr/bin/python2
    layout: even-vertical
    suppress_history: false
    options:
      remain-on-exit: true
    panes:
      - shell: /usr/bin/python3
        shell_command:
          - print('This is python 3')
      - shell: /usr/bin/vim -u none
        shell_command:
          - iAll panes have the `remain-on-exit` setting on.
          - When you exit out of the shell or application, the panes will remain.
          - Use tmux command `:kill-pane` to remove the pane.
          - Use tmux command `:respawn-pane` to restart the shell in the pane.
          - Use <Escape> and then `:q!` to get out of this vim window. :-)
      - shell_command:
          - print('Hello World 2')
      - shell: /usr/bin/top

{
  "session_name": "Pane shell example",
  "windows": [
    {
      "window_name": "first",
      "window_shell": "/usr/bin/python2",
      "layout": "even-vertical",
      "suppress_history": false,
      "options": {
        "remain-on-exit": true
      },
      "panes": [
        {
          "shell": "/usr/bin/python3",
          "shell_command": [
            "print('This is python 3')"
          ]
        },
        {
          "shell": "/usr/bin/vim -u none",
          "shell_command": [
            "iAll panes have the `remain-on-exit` setting on.",
            "When you exit out of the shell or application, the panes will remain.",
            "Use tmux command `:kill-pane` to remove the pane.",
            "Use tmux command `:respawn-pane` to restart the shell in the pane.",
            "Use <Escape> and then `:q!` to get out of this vim window. :-)"
          ]
        },
        {
          "shell_command": [
            "print('Hello World 2')"
          ]
        },
        {
          "shell": "/usr/bin/top"
        }
      ]
    }
  ]
}

layout even-vertical

session_name: Skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # You can see this
          - echo "___$((11 + 1))___"
          # This is skipped
          - cmd: echo "___$((1 + 3))___"
            enter: false

{
  "session_name": "Skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "enter": false
            }
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: Skip command execution (pane-level)
windows:
  - panes:
      - shell_command: echo "___$((1 + 3))___"
        enter: false
      - shell_command:
          - echo "___$((1 + 3))___"\;
          - echo "___$((1 + 3))___"
        enter: false

{
  "session_name": "Skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": "echo \"___$((1 + 3))___\"",
          "enter": false
        },
        {
          "shell_command": [
            "echo \"___$((1 + 3))___\"\\;",
            "echo \"___$((1 + 3))___\""
          ],
          "enter": false
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: Pause / skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # Executes immediately
          - echo "___$((11 + 1))___"
          # Delays before sending 2 seconds
          - cmd: echo "___$((1 + 3))___"
            sleep_before: 2
          # Executes immediately
          - cmd: echo "___$((1 + 3))___"
          # Pauses 2 seconds after
          - cmd: echo "Stuff rendering here!"
            sleep_after: 2
          # Executes after earlier commands (after 2 sec)
          - cmd: echo "2 seconds later"

{
  "session_name": "Pause / skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "sleep_before": 2
            },
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"Stuff rendering here!\"",
              "sleep_after": 2
            },
            {
              "cmd": "echo \"2 seconds later\""
            }
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: Pause / skip command execution (pane-level)
windows:
  - panes:
      - # Wait 2 seconds before sending all commands in this pane
        sleep_before: 2
        shell_command:
          - echo "___$((11 + 1))___"
          - cmd: echo "___$((1 + 3))___"
          - cmd: echo "___$((1 + 3))___"
          - cmd: echo "Stuff rendering here!"
          - cmd: echo "2 seconds later"

{
  "session_name": "Pause / skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "sleep_before": 2,
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"Stuff rendering here!\""
            },
            {
              "cmd": "echo \"2 seconds later\""
            }
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: virtualenv
shell_command_before:
  # - cmd: source $(poetry env info --path)/bin/activate
  # - cmd: source `pipenv --venv`/bin/activate
  - cmd: source .venv/bin/activate
    sleep_before: 1
    sleep_after: 1
windows:
  - panes:
      - shell_command:
          - ./manage.py runserver

{
  "session_name": "virtualenv",
  "shell_command_before": [
    {
      "cmd": "source .venv/bin/activate",
      "sleep_before": 1,
      "sleep_after": 1
    }
  ],
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "./manage.py runserver"
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: suppress
suppress_history: false
windows:
  - window_name: appended
    focus: true
    suppress_history: false
    panes:
      - echo "window in the history!"

  - window_name: suppressed
    suppress_history: true
    panes:
      - echo "window not in the history!"

  - window_name: default
    panes:
      - echo "session in the history!"

  - window_name: mixed
    suppress_history: false
    panes:
      - shell_command:
          - echo "command in the history!"
        suppress_history: false
      - shell_command:
          - echo "command not in the history!"
        suppress_history: true
      - shell_command:
          - echo "window in the history!"

{
  "session_name": "suppress",
  "suppress_history": false,
  "windows": [
    {
      "window_name": "appended",
      "focus": true,
      "suppress_history": false,
      "panes": [
        "echo \"window in the history!\""
      ]
    },
    {
      "window_name": "suppressed",
      "suppress_history": true,
      "panes": [
        "echo \"window not in the history!\""
      ]
    },
    {
      "window_name": "default",
      "panes": [
        "echo \"session in the history!\""
      ]
    },
    {
      "window_name": "mixed",
      "suppress_history": false,
      "panes": [
        {
          "shell_command": [
            "echo \"command in the history!\""
          ],
          "suppress_history": false
        },
        {
          "shell_command": [
            "echo \"command not in the history!\""
          ],
          "suppress_history": true
        },
        {
          "shell_command": [
            "echo \"window in the history!\""
          ]
        }
      ]
    }
  ]
}

no layout set, so the port tiles the panes

session_name: Window index example
windows:
  - window_name: zero
    panes:
      - echo "this window's index will be zero"
  - window_name: five
    panes:
      - echo "this window's index will be five"
    window_index: 5
  - window_name: one
    panes:
      - echo "this window's index will be one"

{
  "session_name": "Window index example",
  "windows": [
    {
      "window_name": "zero",
      "panes": [
        "echo \"this window's index will be zero\""
      ]
    },
    {
      "window_name": "five",
      "panes": [
        "echo \"this window's index will be five\""
      ],
      "window_index": 5
    },
    {
      "window_name": "one",
      "panes": [
        "echo \"this window's index will be one\""
      ]
    }
  ]
}

no layout set, so the port tiles the panes

Install

Install the workspace package separately from the core library.

Dependency cooldowns

The checkbox turns a cooldown on and off for every picker on the site. It applies to what an install pulls in; the package itself, and the libtmux it pins, stay current.

Apply a cooldown of days Bypass any global cooldown

What are cooldowns?

Cooldowns delay picking up newly uploaded packages so the community has time to spot supply-chain attacks before you install. Most package managers don't apply one by default; you opt in through a global setting in your tool's configuration.

Learn more at cooldowns.dev · Datadog Security Labs writeup.

$ npx -y @libtmux/workspace-cli --help

$ npx -y @libtmux/workspace-cli --help

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release this runs. This command runs without one.

$ npx -y --min-release-age=0 @libtmux/workspace-cli --help

Runs tmux-workspace without installing it. Pass a command such as load ./workspace.yaml in place of --help.

$ bunx --bun @libtmux/workspace-cli --help

$ bunx --bun @libtmux/workspace-cli --help

Bun cannot exempt @libtmux/workspace-cli from its own cooldown, so a cooldown here would also hold back the release this installs. This command runs without one.

$ bunx --bun --minimum-release-age=0 @libtmux/workspace-cli --help

--bun runs the command on Bun. Without it, bunx runs the command on Node when Node is installed, because its shebang names node.

$ pnpm dlx @libtmux/workspace-cli --help

$ EXCLUDE='["@libtmux/workspace-cli","libtmux"]' && \
pnpm_config_minimum_release_age=10080 \
    pnpm_config_minimum_release_age_exclude="$EXCLUDE" \
    pnpm dlx @libtmux/workspace-cli --help

$ pnpm_config_minimum_release_age=0 pnpm dlx @libtmux/workspace-cli --help

$ yarn dlx @libtmux/workspace-cli --help

$ YARN_NPM_MINIMAL_AGE_GATE=7d \
    YARN_NPM_PREAPPROVED_PACKAGES=@libtmux/workspace-cli,libtmux \
    yarn dlx @libtmux/workspace-cli --help

$ YARN_NPM_MINIMAL_AGE_GATE=0 yarn dlx @libtmux/workspace-cli --help

Yarn refuses a release younger than its npmMinimalAgeGate, one day by default.

$ npm install -g @libtmux/workspace-cli

$ npm install -g \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/workspace-cli \
    --min-release-age-exclude=libtmux \
    @libtmux/workspace-cli

$ npm install -g --min-release-age=0 @libtmux/workspace-cli

Puts tmux-workspace on PATH, so a workspace loads with tmux-workspace load ./workspace.yaml.

$ pnpm add -g @libtmux/workspace-cli

$ EXCLUDE='["@libtmux/workspace-cli","libtmux"]' && \
pnpm_config_minimum_release_age=10080 \
    pnpm_config_minimum_release_age_exclude="$EXCLUDE" \
    pnpm add -g @libtmux/workspace-cli

$ pnpm_config_minimum_release_age=0 pnpm add -g @libtmux/workspace-cli

$ bun add -g @libtmux/workspace-cli

$ bun add -g @libtmux/workspace-cli

Bun cannot exempt @libtmux/workspace-cli from its own cooldown, so a cooldown here would also hold back the release this installs. This command runs without one.

$ bun add -g --minimum-release-age=0 @libtmux/workspace-cli

CLI Manual

Commands, options and machine output.

Configuration

Workspace fields, normalization and execution.

Install and load

Load a workspace on a private socket, then capture it.

Example gallery

Workspace files to start from, with their prerequisites.

Runtime support

Runtime requirements and supported behavior.

Internals

The workspace library, for building sessions from code.

tmux-workspace creates tmux sessions from YAML or JSON. A file describes windows, panes, commands, directories and environment. Load it from a terminal or request machine output for automation.

Load a workspace from the terminal¶

The CLI manual covers discovery, search, editing, loading, capture, conversion and import. Examples provide complete configurations with their prerequisites.

Automate and inspect¶

Use load -d when the caller should return without attaching. --json returns a result, and --ndjson supports a stream of records. Read automation for retry and cleanup decisions and errors for failure handling.

Loaded workspaces are ordinary tmux sessions. Select the same socket when inspecting them from tmux or the MCP server.

Build from application code¶

The workspace library has its own API and configuration contract. Use it when a program needs direct control over construction. The CLI task guides here describe the tmux-workspace executable and link to its documented source revision.

CLI source.

Example workspaces

Each workspace below is a file that libtmux/libtmux-ts loads in a test or a scheduled run, as the list under it says. The drawing shows the panes of each window and the commands each pane receives.

Short-hand panes

A pane can be one command written as a string, and a command list can be one string.

session_name: shorthands
windows:
  - window_name: long form
    panes:
      - shell_command:
          - echo 'did you know'
          - echo 'you can inline'
      - shell_command: echo 'single commands'
      - echo 'for panes'

{
  "session_name": "shorthands",
  "windows": [
    {
      "window_name": "long form",
      "panes": [
        {
          "shell_command": [
            "echo 'did you know'",
            "echo 'you can inline'"
          ]
        },
        {
          "shell_command": "echo 'single commands'"
        },
        "echo 'for panes'"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:long form

no layout set, so the port tiles the panes

Same file as tmuxp's examples/shorthands.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/shorthands.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Two panes

A window of two panes.

session_name: 2-pane-vertical
windows:
  - window_name: my test window
    panes:
      - echo hello
      - echo hello

{
  "session_name": "2-pane-vertical",
  "windows": [
    {
      "window_name": "my test window",
      "panes": [
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:my test window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/2-pane-vertical.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/2-pane-vertical.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Three panes

A window of three panes.

Also shows: setup before each pane

session_name: 3-panes
windows:
  - window_name: dev window
    layout: main-vertical
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello

{
  "session_name": "3-panes",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "main-vertical",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:dev window

layout main-vertical

Same file as tmuxp's examples/3-pane.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/3-pane.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Four panes

A window of four panes.

Also shows: tiled layout

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo hello
      - echo hello
      - echo hello

{
  "session_name": "4-pane-split",
  "windows": [
    {
      "window_name": "dev window",
      "layout": "tiled",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep \\.log"
          ]
        },
        "echo hello",
        "echo hello",
        "echo hello"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:dev window

layout tiled

Same file as tmuxp's examples/4-pane.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/4-pane.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Main-horizontal layout

The main-horizontal layout gives the first pane the top of the window and splits the rest below it.

Also shows: three panes

session_name: main-pane-height
start_directory: "~"
windows:
  - layout: main-horizontal
    options:
      main-pane-height: 30
    panes:
      - shell_command:
          - top
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"
    window_name: my window name

{
  "session_name": "main-pane-height",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": 30
      },
      "panes": [
        {
          "shell_command": [
            "top"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ],
      "window_name": "my window name"
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:my window name

layout main-horizontal

Same file as tmuxp's examples/main-pane-height.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/main-pane-height.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Environment

environment sets variables for a session, a window or a pane.

session_name: Environment variables test
environment:
  EDITOR: /usr/bin/vim
  DJANGO_SETTINGS_MODULE: my_app.settings.local
  SERVER_PORT: "8009"
windows:
  - window_name: Django project
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
  - window_name: Another Django project
    environment:
      DJANGO_SETTINGS_MODULE: my_app.settings.local
      SERVER_PORT: "8010"
    panes:
      - ./manage.py runserver 0.0.0.0:${SERVER_PORT}
      - environment:
          DJANGO_SETTINGS_MODULE: my_app.settings.local-testing
          SERVER_PORT: "8011"
        shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT}

{
  "session_name": "Environment variables test",
  "environment": {
    "EDITOR": "/usr/bin/vim",
    "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
    "SERVER_PORT": "8009"
  },
  "windows": [
    {
      "window_name": "Django project",
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
      ]
    },
    {
      "window_name": "Another Django project",
      "environment": {
        "DJANGO_SETTINGS_MODULE": "my_app.settings.local",
        "SERVER_PORT": "8010"
      },
      "panes": [
        "./manage.py runserver 0.0.0.0:${SERVER_PORT}",
        {
          "environment": {
            "DJANGO_SETTINGS_MODULE": "my_app.settings.local-testing",
            "SERVER_PORT": "8011"
          },
          "shell_command": "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:Django project

no layout set, so the port tiles the panes

1:Another Django project

no layout set, so the port tiles the panes

Same file as tmuxp's examples/session-environment.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/session-environment.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Start directory

start_directory chooses where a session, a window or a pane starts.

session_name: start directory
start_directory: /var/
windows:
  - window_name: should be /var/
    panes:
      - shell_command:
          - echo "\033c
          - it trickles down from session-level"
      - echo hello
  - window_name: should be /var/log
    start_directory: log
    panes:
      - shell_command:
          - echo '\033c
          - window start_directory concatenates to session start_directory
          - if it is not absolute'
      - echo hello
  - window_name: should be ~
    start_directory: "~"
    panes:
      - shell_command:
          - 'echo \\033c ~ has precedence. note: remember to quote ~ in YAML'
      - echo hello
  - window_name: should be /bin
    start_directory: /bin
    panes:
      - echo '\033c absolute paths also have precedence.'
      - echo hello
  - window_name: should be workspace file's dir

    start_directory: ./
    panes:
      - shell_command:
          - echo '\033c
          - ./ is relative to workspace file location
          - ../ will be parent of workspace file
          - ./test will be \"test\" dir inside dir of workspace file'
      - shell_command:
          - echo '\033c
          - This way you can load up workspaces from projects and maintain
          - relative paths.'

{
  "session_name": "start directory",
  "start_directory": "/var/",
  "windows": [
    {
      "window_name": "should be /var/",
      "panes": [
        {
          "shell_command": [
            "echo \"\\033c",
            "it trickles down from session-level\""
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be /var/log",
      "start_directory": "log",
      "panes": [
        {
          "shell_command": [
            "echo '\\033c",
            "window start_directory concatenates to session start_directory",
            "if it is not absolute'"
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be ~",
      "start_directory": "~",
      "panes": [
        {
          "shell_command": [
            "echo \\\\033c ~ has precedence. note: remember to quote ~ in YAML"
          ]
        },
        "echo hello"
      ]
    },
    {
      "window_name": "should be /bin",
      "start_directory": "/bin",
      "panes": [
        "echo '\\033c absolute paths also have precedence.'",
        "echo hello"
      ]
    },
    {
      "window_name": "should be workspace file's dir",
      "start_directory": "./",
      "panes": [
        {
          "shell_command": [
            "echo '\\033c",
            "./ is relative to workspace file location",
            "../ will be parent of workspace file",
            "./test will be \\\"test\\\" dir inside dir of workspace file'"
          ]
        },
        {
          "shell_command": [
            "echo '\\033c",
            "This way you can load up workspaces from projects and maintain",
            "relative paths.'"
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:should be /var/

no layout set, so the port tiles the panes

1:should be /var/log

no layout set, so the port tiles the panes

2:should be ~

no layout set, so the port tiles the panes

3:should be /bin

no layout set, so the port tiles the panes

4:should be workspace file's dir

no layout set, so the port tiles the panes

Same file as tmuxp's examples/start-directory.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/start-directory.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Synchronized panes

options_after sets synchronize-panes once the panes exist, so typing in one pane reaches the others.

session_name: 2-pane-synchronized
windows:
  - window_name: Two synchronized panes
    panes:
      - ssh server1
      - ssh server2
    options_after:
      synchronize-panes: on

{
  "session_name": "2-pane-synchronized",
  "windows": [
    {
      "window_name": "Two synchronized panes",
      "panes": [
        "ssh server1",
        "ssh server2"
      ],
      "options_after": {
        "synchronize-panes": "on"
      }
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:Two synchronized panes

no layout set, so the port tiles the panes

Same file as tmuxp's examples/2-pane-synchronized.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/2-pane-synchronized.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Blank panes

An empty entry, null, pane or blank opens a pane with no command.

Also shows: start directory

session_name: Blank pane test
windows:
  # Emptiness will simply open a blank pane, if no shell_command_before.
  # All these are equivalent
  - window_name: Blank pane test
    panes:
      -
      - pane
      - blank
  - window_name: More blank panes
    panes:
      - null
      - shell_command:
      - shell_command:
          -
  # an empty string will be treated as a carriage return
  - window_name: Empty string (return)
    panes:
      - ""
      - shell_command: ""
      - shell_command:
          - ""
  # a pane can have other options but still be blank
  - window_name: Blank with options
    panes:
      - focus: true
      - start_directory: /tmp

{
  "session_name": "Blank pane test",
  "windows": [
    {
      "window_name": "Blank pane test",
      "panes": [
        null,
        "pane",
        "blank"
      ]
    },
    {
      "window_name": "More blank panes",
      "panes": [
        null,
        {
          "shell_command": null
        },
        {
          "shell_command": [
            null
          ]
        }
      ]
    },
    {
      "window_name": "Empty string (return)",
      "panes": [
        "",
        {
          "shell_command": ""
        },
        {
          "shell_command": [
            ""
          ]
        }
      ]
    },
    {
      "window_name": "Blank with options",
      "panes": [
        {
          "focus": true
        },
        {
          "start_directory": "/tmp"
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:Blank pane test

no layout set, so the port tiles the panes

1:More blank panes

no layout set, so the port tiles the panes

2:Empty string (return)

no layout set, so the port tiles the panes

3:Blank with options

no layout set, so the port tiles the panes

Same file as tmuxp's examples/blank-panes.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/blank-panes.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Variables in values

A ${VAR} in a name, a path or an option expands from the environment of the loading process.

Also shows: start directory

start_directory: "${PWD}/test"
shell_command_before: "echo ${PWD}"
before_script: "${MY_ENV_VAR}/test3.sh"
session_name: session - ${USER} (${MY_ENV_VAR})
windows:
  - window_name: editor
    panes:
      - shell_command:
          - tail -F /var/log/syslog
    start_directory: /var/log
  - window_name: logging for ${USER}
    options:
      automatic-rename: true
    panes:
      - shell_command:
          - htop
          - ls $PWD

{
  "start_directory": "${PWD}/test",
  "shell_command_before": "echo ${PWD}",
  "before_script": "${MY_ENV_VAR}/test3.sh",
  "session_name": "session - ${USER} (${MY_ENV_VAR})",
  "windows": [
    {
      "window_name": "editor",
      "panes": [
        {
          "shell_command": [
            "tail -F /var/log/syslog"
          ]
        }
      ],
      "start_directory": "/var/log"
    },
    {
      "window_name": "logging for ${USER}",
      "options": {
        "automatic-rename": true
      },
      "panes": [
        {
          "shell_command": [
            "htop",
            "ls $PWD"
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:editor

no layout set, so the port tiles the panes

1:logging for ${USER}

no layout set, so the port tiles the panes

The test supplies MY_ENV_VAR, PWD and USER and a before_script that leaves a marker; the file loads as written.

Same file as tmuxp's examples/env-variables.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/env-variables.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Focus

focus: true selects a window or a pane when the session is built.

Also shows: setup before each pane

session_name: focus
windows:
  - window_name: attached window
    focus: true
    panes:
      - shell_command:
          - echo hello
          - echo 'this pane should be selected on load'
        focus: true
      - shell_command:
          - cd /var/log
          - echo hello
  - window_name: second window
    shell_command_before: cd /var/log
    panes:
      - pane
      - shell_command:
          - echo 'this pane should be focused, when window switched to first time'
        focus: true
      - pane

{
  "session_name": "focus",
  "windows": [
    {
      "window_name": "attached window",
      "focus": true,
      "panes": [
        {
          "shell_command": [
            "echo hello",
            "echo 'this pane should be selected on load'"
          ],
          "focus": true
        },
        {
          "shell_command": [
            "cd /var/log",
            "echo hello"
          ]
        }
      ]
    },
    {
      "window_name": "second window",
      "shell_command_before": "cd /var/log",
      "panes": [
        "pane",
        {
          "shell_command": [
            "echo 'this pane should be focused, when window switched to first time'"
          ],
          "focus": true
        },
        "pane"
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:attached window

no layout set, so the port tiles the panes

1:second window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/focus-window-and-panes.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/focus-window-and-panes.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Main pane height as a percentage

main-pane-height takes a percentage of the window as well as a row count.

Also shows: three panes, main-horizontal layout, start directory

session_name: main-pane-height
start_directory: "~"
windows:
  - layout: main-horizontal
    options:
      main-pane-height: 67%
    panes:
      - shell_command:
          - top
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"
    window_name: my window name

{
  "session_name": "main-pane-height",
  "start_directory": "~",
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "main-pane-height": "67%"
      },
      "panes": [
        {
          "shell_command": [
            "top"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ],
      "window_name": "my window name"
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:my window name

layout main-horizontal

Same file as tmuxp's examples/main-pane-height-percentage.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/main-pane-height-percentage.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Minimal workspace

A session name and one window with one blank pane.

session_name: My tmux session
windows:
  - panes:
      -

{
  "session_name": "My tmux session",
  "windows": [
    {
      "panes": [
        null
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/minimal.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/minimal.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

tmux options

global_options, options and a window's options set tmux options.

Also shows: main-horizontal layout, three panes, start directory

session_name: test window options
start_directory: "~"
global_options:
  default-shell: /bin/sh
  default-command: /bin/sh
options:
  main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variables
windows:
  - layout: main-horizontal
    options:
      automatic-rename: on
    panes:
      - shell_command:
          - man echo
        start_directory: "~"
      - shell_command:
          - echo "hey"
      - shell_command:
          - echo "moo"

{
  "session_name": "test window options",
  "start_directory": "~",
  "global_options": {
    "default-shell": "/bin/sh",
    "default-command": "/bin/sh"
  },
  "options": {
    "main-pane-height": "${MAIN_PANE_HEIGHT}"
  },
  "windows": [
    {
      "layout": "main-horizontal",
      "options": {
        "automatic-rename": "on"
      },
      "panes": [
        {
          "shell_command": [
            "man echo"
          ],
          "start_directory": "~"
        },
        {
          "shell_command": [
            "echo \"hey\""
          ]
        },
        {
          "shell_command": [
            "echo \"moo\""
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

layout main-horizontal

The test supplies MAIN_PANE_HEIGHT, which the file reads from the environment; the file loads as written.

Same file as tmuxp's examples/options.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/options.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Shell per pane

A pane can start its own shell or program, and window_shell sets the default for a window.

session_name: Pane shell example
windows:
  - window_name: first
    window_shell: /usr/bin/python2
    layout: even-vertical
    suppress_history: false
    options:
      remain-on-exit: true
    panes:
      - shell: /usr/bin/python3
        shell_command:
          - print('This is python 3')
      - shell: /usr/bin/vim -u none
        shell_command:
          - iAll panes have the `remain-on-exit` setting on.
          - When you exit out of the shell or application, the panes will remain.
          - Use tmux command `:kill-pane` to remove the pane.
          - Use tmux command `:respawn-pane` to restart the shell in the pane.
          - Use <Escape> and then `:q!` to get out of this vim window. :-)
      - shell_command:
          - print('Hello World 2')
      - shell: /usr/bin/top

{
  "session_name": "Pane shell example",
  "windows": [
    {
      "window_name": "first",
      "window_shell": "/usr/bin/python2",
      "layout": "even-vertical",
      "suppress_history": false,
      "options": {
        "remain-on-exit": true
      },
      "panes": [
        {
          "shell": "/usr/bin/python3",
          "shell_command": [
            "print('This is python 3')"
          ]
        },
        {
          "shell": "/usr/bin/vim -u none",
          "shell_command": [
            "iAll panes have the `remain-on-exit` setting on.",
            "When you exit out of the shell or application, the panes will remain.",
            "Use tmux command `:kill-pane` to remove the pane.",
            "Use tmux command `:respawn-pane` to restart the shell in the pane.",
            "Use <Escape> and then `:q!` to get out of this vim window. :-)"
          ]
        },
        {
          "shell_command": [
            "print('Hello World 2')"
          ]
        },
        {
          "shell": "/usr/bin/top"
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:first

layout even-vertical

Same file as tmuxp's examples/pane-shell.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/pane-shell.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Skip Enter for a command

enter: false types a command without running it.

session_name: Skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # You can see this
          - echo "___$((11 + 1))___"
          # This is skipped
          - cmd: echo "___$((1 + 3))___"
            enter: false

{
  "session_name": "Skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "enter": false
            }
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/skip-send.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/skip-send.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Skip Enter for a pane

enter: false on a pane types its commands without running them.

session_name: Skip command execution (pane-level)
windows:
  - panes:
      - shell_command: echo "___$((1 + 3))___"
        enter: false
      - shell_command:
          - echo "___$((1 + 3))___"\;
          - echo "___$((1 + 3))___"
        enter: false

{
  "session_name": "Skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": "echo \"___$((1 + 3))___\"",
          "enter": false
        },
        {
          "shell_command": [
            "echo \"___$((1 + 3))___\"\\;",
            "echo \"___$((1 + 3))___\""
          ],
          "enter": false
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/skip-send-pane-level.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/skip-send-pane-level.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Pause around a command

sleep_before and sleep_after delay a command or the one after it.

session_name: Pause / skip command execution (command-level)
windows:
  - panes:
      - shell_command:
          # Executes immediately
          - echo "___$((11 + 1))___"
          # Delays before sending 2 seconds
          - cmd: echo "___$((1 + 3))___"
            sleep_before: 2
          # Executes immediately
          - cmd: echo "___$((1 + 3))___"
          # Pauses 2 seconds after
          - cmd: echo "Stuff rendering here!"
            sleep_after: 2
          # Executes after earlier commands (after 2 sec)
          - cmd: echo "2 seconds later"

{
  "session_name": "Pause / skip command execution (command-level)",
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\"",
              "sleep_before": 2
            },
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"Stuff rendering here!\"",
              "sleep_after": 2
            },
            {
              "cmd": "echo \"2 seconds later\""
            }
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/sleep.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Pause before a pane

sleep_before on a pane waits before it sends any of its commands.

session_name: Pause / skip command execution (pane-level)
windows:
  - panes:
      - # Wait 2 seconds before sending all commands in this pane
        sleep_before: 2
        shell_command:
          - echo "___$((11 + 1))___"
          - cmd: echo "___$((1 + 3))___"
          - cmd: echo "___$((1 + 3))___"
          - cmd: echo "Stuff rendering here!"
          - cmd: echo "2 seconds later"

{
  "session_name": "Pause / skip command execution (pane-level)",
  "windows": [
    {
      "panes": [
        {
          "sleep_before": 2,
          "shell_command": [
            "echo \"___$((11 + 1))___\"",
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"___$((1 + 3))___\""
            },
            {
              "cmd": "echo \"Stuff rendering here!\""
            },
            {
              "cmd": "echo \"2 seconds later\""
            }
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/sleep-pane-level.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep-pane-level.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Wait for a virtualenv

A setup command with sleep_before and sleep_after gives a virtualenv time to activate before the commands run.

Also shows: setup before each pane

session_name: virtualenv
shell_command_before:
  # - cmd: source $(poetry env info --path)/bin/activate
  # - cmd: source `pipenv --venv`/bin/activate
  - cmd: source .venv/bin/activate
    sleep_before: 1
    sleep_after: 1
windows:
  - panes:
      - shell_command:
          - ./manage.py runserver

{
  "session_name": "virtualenv",
  "shell_command_before": [
    {
      "cmd": "source .venv/bin/activate",
      "sleep_before": 1,
      "sleep_after": 1
    }
  ],
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "./manage.py runserver"
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:window

no layout set, so the port tiles the panes

Same file as tmuxp's examples/sleep-virtualenv.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep-virtualenv.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Keep commands out of history

suppress_history chooses whether commands reach the shell history, per session, window, pane or command.

session_name: suppress
suppress_history: false
windows:
  - window_name: appended
    focus: true
    suppress_history: false
    panes:
      - echo "window in the history!"

  - window_name: suppressed
    suppress_history: true
    panes:
      - echo "window not in the history!"

  - window_name: default
    panes:
      - echo "session in the history!"

  - window_name: mixed
    suppress_history: false
    panes:
      - shell_command:
          - echo "command in the history!"
        suppress_history: false
      - shell_command:
          - echo "command not in the history!"
        suppress_history: true
      - shell_command:
          - echo "window in the history!"

{
  "session_name": "suppress",
  "suppress_history": false,
  "windows": [
    {
      "window_name": "appended",
      "focus": true,
      "suppress_history": false,
      "panes": [
        "echo \"window in the history!\""
      ]
    },
    {
      "window_name": "suppressed",
      "suppress_history": true,
      "panes": [
        "echo \"window not in the history!\""
      ]
    },
    {
      "window_name": "default",
      "panes": [
        "echo \"session in the history!\""
      ]
    },
    {
      "window_name": "mixed",
      "suppress_history": false,
      "panes": [
        {
          "shell_command": [
            "echo \"command in the history!\""
          ],
          "suppress_history": false
        },
        {
          "shell_command": [
            "echo \"command not in the history!\""
          ],
          "suppress_history": true
        },
        {
          "shell_command": [
            "echo \"window in the history!\""
          ]
        }
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:appended

no layout set, so the port tiles the panes

1:suppressed

no layout set, so the port tiles the panes

2:default

no layout set, so the port tiles the panes

3:mixed

no layout set, so the port tiles the panes

Same file as tmuxp's examples/suppress-history.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/suppress-history.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)

Window index

window_index places a window at an index; a window without one takes the lowest free index.

session_name: Window index example
windows:
  - window_name: zero
    panes:
      - echo "this window's index will be zero"
  - window_name: five
    panes:
      - echo "this window's index will be five"
    window_index: 5
  - window_name: one
    panes:
      - echo "this window's index will be one"

{
  "session_name": "Window index example",
  "windows": [
    {
      "window_name": "zero",
      "panes": [
        "echo \"this window's index will be zero\""
      ]
    },
    {
      "window_name": "five",
      "panes": [
        "echo \"this window's index will be five\""
      ],
      "window_index": 5
    },
    {
      "window_name": "one",
      "panes": [
        "echo \"this window's index will be one\""
      ]
    }
  ]
}

Converted from the YAML; the tests load the YAML.

0:zero

no layout set, so the port tiles the panes

1:one

no layout set, so the port tiles the panes

5:five

no layout set, so the port tiles the panes

Same file as tmuxp's examples/window-index.yaml.

Source: packages/workspace-cli/tests/fixtures/tmuxp-examples/window-index.yaml

Loaded by:

every tmuxp example workspace loads through the CLI: Runs the CLI's load -d on each of tmuxp's example files, each on its own tmux server, and checks the session, the windows and the panes tmux reports. (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command)