Workspace ManagerconceptHome

Choose documentation 3

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

Edit this page on GitHub

tmux workspace manager, forged in C++.

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

Explore tmux layout / workspace possibilities

Preset
Short-hand panesTwo panesThree panesFour panesMain-horizontal layoutEnvironmentStart directorySynchronized panesBlank panesFocusMain pane height as a percentageMinimal workspacetmux optionsShell per paneSkip Enter for a commandSkip Enter for a panePause around a commandPause before a paneWait for a virtualenvKeep commands out of historyWindow index

Choose a preset 21

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'"
]
}
]
}
Window 0, long form: 3 panes, even-vertical❯ echo 'did you know'❯ echo 'you can inline'❯ echo 'single commands'❯ echo 'for panes'
no layout set
session_name: work
start_directory: /tmp
windows:
- window_name: editor
layout: main-vertical
panes:
- shell_command:
- echo first
- echo second
- echo lone
- window_name: logs
root: /
panes:
- shell_command: echo tail
-
{
"session_name": "work",
"start_directory": "/tmp",
"windows": [
{
"window_name": "editor",
"layout": "main-vertical",
"panes": [
{
"shell_command": [
"echo first",
"echo second"
]
},
"echo lone"
]
},
{
"window_name": "logs",
"root": "/",
"panes": [
{
"shell_command": "echo tail"
},
null
]
}
]
}
Window 0, editor: 2 panes, main-vertical❯ echo first❯ echo second❯ echo lone
layout main-vertical
Window 1, logs: 2 panes, even-vertical❯ echo tail
no layout set
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"
]
}
]
}
Window 0, dev window: 3 panes, main-vertical❯ 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"
]
}
]
}
Window 0, dev window: 4 panes, tiled❯ cd /var/log❯ ls -al | grep \.log❯ echo hello❯ echo hello❯ echo hello
layout tiled
session_name: libtmux
start_directory: /tmp
shell_command_before:
- echo setup
windows:
- window_name: work
focus: True
layout: main-horizontal
options:
main-pane-height: 60%
panes:
- focus: true
- echo second
- window_name: docs
shell_command_before: echo docs-setup
panes:
- echo only
{
"session_name": "libtmux",
"start_directory": "/tmp",
"shell_command_before": [
"echo setup"
],
"windows": [
{
"window_name": "work",
"focus": true,
"layout": "main-horizontal",
"options": {
"main-pane-height": "60%"
},
"panes": [
{
"focus": true
},
"echo second"
]
},
{
"window_name": "docs",
"shell_command_before": "echo docs-setup",
"panes": [
"echo only"
]
}
]
}
Window 0, work: 2 panes, main-horizontal❯ echo second
layout main-horizontal
Window 1, docs: 1 pane, even-vertical❯ echo only
no layout set
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}"
}
]
}
]
}
Window 0, Django project: 1 pane, even-vertical❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set
Window 1, Another Django project: 2 panes, even-vertical❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set
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.'"
]
}
]
}
]
}
Window 0, should be /var/: 2 panes, even-vertical❯ echo "\033c❯ it trickles down from session-level"❯ echo hello
no layout set
Window 1, should be /var/log: 2 panes, even-vertical❯ echo '\033c❯ window start_directory concatenates to session start_directory❯ if it is not absolute'❯ echo hello
no layout set
Window 2, should be ~: 2 panes, even-vertical❯ echo \\033c ~ has precedence. note: remember to quote ~ in YAML❯ echo hello
no layout set
Window 3, should be /bin: 2 panes, even-vertical❯ echo '\033c absolute paths also have precedence.'❯ echo hello
no layout set
Window 4, should be workspace file's dir: 2 panes, even-vertical❯ echo '\033c❯ ./ is relative to workspace file location❯ ../ will be parent of workspace file❯ ./test will be \"test\" dir inside dir of workspace file'❯ echo '\033c❯ This way you can load up workspaces from projects and maintain❯ relative paths.'
no layout set
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"
}
}
]
}
Window 0, Two synchronized panes: 2 panes, even-vertical❯ ssh server1❯ ssh server2
no layout set
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"
}
]
}
]
}
Window 0, Blank pane test: 3 panes, even-vertical
no layout set
Window 1, More blank panes: 3 panes, even-vertical
no layout set
Window 2, Empty string (return): 3 panes, even-vertical
no layout set
Window 3, Blank with options: 2 panes, even-vertical
no layout set
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"
]
}
]
}
Window 0, attached window: 2 panes, even-vertical❯ echo hello❯ echo 'this pane should be selected on load'❯ cd /var/log❯ echo hello
no layout set
Window 1, second window: 3 panes, even-vertical❯ echo 'this pane should be focused, when window switched to first time'
no layout set
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"
}
]
}
Window 0, my window name: 3 panes, main-horizontal❯ top❯ echo "hey"❯ echo "moo"
layout main-horizontal
session_name: My tmux session
windows:
- panes:
-
{
"session_name": "My tmux session",
"windows": [
{
"panes": [
null
]
}
]
}
Window 0: 1 pane, even-vertical
no layout set
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\""
]
}
]
}
]
}
Window 0: 3 panes, main-horizontal❯ man echo❯ echo "hey"❯ 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"
}
]
}
]
}
Window 0, first: 4 panes, even-vertical❯ print('This is python 3')❯ 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. :-)❯ print('Hello World 2')
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
}
]
}
]
}
]
}
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"
no layout set
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
}
]
}
]
}
Window 0: 2 panes, even-vertical❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"\;❯ echo "___$((1 + 3))___"
no layout set
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\""
}
]
}
]
}
]
}
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set
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\""
}
]
}
]
}
]
}
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set
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"
]
}
]
}
]
}
Window 0: 1 pane, even-vertical❯ ./manage.py runserver
no layout set
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!\""
]
}
]
}
]
}
Window 0, appended: 1 pane, even-vertical❯ echo "window in the history!"
no layout set
Window 1, suppressed: 1 pane, even-vertical❯ echo "window not in the history!"
no layout set
Window 2, default: 1 pane, even-vertical❯ echo "session in the history!"
no layout set
Window 3, mixed: 3 panes, even-vertical❯ echo "command in the history!"❯ echo "command not in the history!"❯ echo "window in the history!"
no layout set
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\""
]
}
]
}
Window 0, zero: 1 pane, even-vertical❯ echo "this window's index will be zero"
no layout set
Window 1, one: 1 pane, even-vertical❯ echo "this window's index will be one"
no layout set
Window 5, five: 1 pane, even-vertical❯ echo "this window's index will be five"
no layout set

Install

Install the workspace package separately from the core library.

$ cmake --preset cxx-dev -DLIBTMUX_BUILD_WORKSPACE_CLI=ON && \
    cmake --build --preset cxx-dev --target tmux-workspace --parallel 2

Run from a libtmux-cxx checkout with Clang 18.1.3, libc++ 18.1, CMake 3.25 or newer, and Ninja. The command is build/cxx-dev/apps/workspace/tmux-workspace.

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

  1. Install the command and load a workspace.
  2. Configure windows and panes.
  3. Capture and reload a session.

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-cxx 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
Window 0, long form: 3 panes, even-vertical❯ echo 'did you know'❯ echo 'you can inline'❯ echo 'single commands'❯ echo 'for panes'
no layout set

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

Source: examples/workspace/tests/fixtures/tmuxp/shorthands.yaml

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

Two panes

A window of two panes.

Also shows: start directory

session_name: work
start_directory: /tmp
windows:
- window_name: editor
layout: main-vertical
panes:
- shell_command:
- echo first
- echo second
- echo lone
- window_name: logs
root: /
panes:
- shell_command: echo tail
-
{
"session_name": "work",
"start_directory": "/tmp",
"windows": [
{
"window_name": "editor",
"layout": "main-vertical",
"panes": [
{
"shell_command": [
"echo first",
"echo second"
]
},
"echo lone"
]
},
{
"window_name": "logs",
"root": "/",
"panes": [
{
"shell_command": "echo tail"
},
null
]
}
]
}

Converted from the YAML; the tests load the YAML.

0:editor
Window 0, editor: 2 panes, main-vertical❯ echo first❯ echo second❯ echo lone
layout main-vertical
1:logs
Window 1, logs: 2 panes, even-vertical❯ echo tail
no layout set

Source: examples/workspace/tests/tmuxp_test.cpp

Loaded by:

  • ADocumentBecomesAWorkspace: Parses the document with parse_tmuxp and checks the names, layout, commands and start directory. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)
  • AParsedDocumentBuildsOnARealServer: Builds the document on a real tmux server and checks the window count, the pane count and each pane's directory. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, dev window: 3 panes, main-vertical❯ cd /var/log❯ ls -al | grep \.log❯ echo hello❯ echo hello
layout main-vertical

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, dev window: 4 panes, tiled❯ cd /var/log❯ ls -al | grep \.log❯ echo hello❯ echo hello❯ echo hello
layout tiled

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

Main-horizontal layout

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

Also shows: setup before each pane, start directory

session_name: libtmux
start_directory: /tmp
shell_command_before:
- echo setup
windows:
- window_name: work
focus: True
layout: main-horizontal
options:
main-pane-height: 60%
panes:
- focus: true
- echo second
- window_name: docs
shell_command_before: echo docs-setup
panes:
- echo only
{
"session_name": "libtmux",
"start_directory": "/tmp",
"shell_command_before": [
"echo setup"
],
"windows": [
{
"window_name": "work",
"focus": true,
"layout": "main-horizontal",
"options": {
"main-pane-height": "60%"
},
"panes": [
{
"focus": true
},
"echo second"
]
},
{
"window_name": "docs",
"shell_command_before": "echo docs-setup",
"panes": [
"echo only"
]
}
]
}

Converted from the YAML; the tests load the YAML.

0:work
Window 0, work: 2 panes, main-horizontal❯ echo second
layout main-horizontal
1:docs
Window 1, docs: 1 pane, even-vertical❯ echo only
no layout set

Source: examples/workspace/tests/tmuxp_test.cpp

Loaded by:

  • EveryKeyTheDocumentCarriesReachesTheWorkspace: Parses the document and checks the setup commands, focus and the main-pane-height option. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)
  • FocusAndOptionsLandOnTheBuiltSession: Builds the document on a real tmux server and checks the active window, the main-pane-height option and the pane count. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, Django project: 1 pane, even-vertical❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set
1:Another Django project
Window 1, Another Django project: 2 panes, even-vertical❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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/
Window 0, should be /var/: 2 panes, even-vertical❯ echo "\033c❯ it trickles down from session-level"❯ echo hello
no layout set
1:should be /var/log
Window 1, should be /var/log: 2 panes, even-vertical❯ echo '\033c❯ window start_directory concatenates to session start_directory❯ if it is not absolute'❯ echo hello
no layout set
2:should be ~
Window 2, should be ~: 2 panes, even-vertical❯ echo \\033c ~ has precedence. note: remember to quote ~ in YAML❯ echo hello
no layout set
3:should be /bin
Window 3, should be /bin: 2 panes, even-vertical❯ echo '\033c absolute paths also have precedence.'❯ echo hello
no layout set
4:should be workspace file's dir
Window 4, should be workspace file's dir: 2 panes, even-vertical❯ echo '\033c❯ ./ is relative to workspace file location❯ ../ will be parent of workspace file❯ ./test will be \"test\" dir inside dir of workspace file'❯ echo '\033c❯ This way you can load up workspaces from projects and maintain❯ relative paths.'
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, Two synchronized panes: 2 panes, even-vertical❯ ssh server1❯ ssh server2
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, Blank pane test: 3 panes, even-vertical
no layout set
1:More blank panes
Window 1, More blank panes: 3 panes, even-vertical
no layout set
2:Empty string (return)
Window 2, Empty string (return): 3 panes, even-vertical
no layout set
3:Blank with options
Window 3, Blank with options: 2 panes, even-vertical
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, attached window: 2 panes, even-vertical❯ echo hello❯ echo 'this pane should be selected on load'❯ cd /var/log❯ echo hello
no layout set
1:second window
Window 1, second window: 3 panes, even-vertical❯ echo 'this pane should be focused, when window switched to first time'
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, my window name: 3 panes, main-horizontal❯ top❯ echo "hey"❯ echo "moo"
layout main-horizontal

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 1 pane, even-vertical
no layout set

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

Source: examples/workspace/tests/fixtures/tmuxp/minimal.yaml

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 3 panes, main-horizontal❯ man echo❯ echo "hey"❯ echo "moo"
layout main-horizontal

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

Source: examples/workspace/tests/fixtures/tmuxp/options.yaml

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, first: 4 panes, even-vertical❯ print('This is python 3')❯ 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. :-)❯ print('Hello World 2')
layout even-vertical

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 2 panes, even-vertical❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"\;❯ echo "___$((1 + 3))___"
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set

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

Source: examples/workspace/tests/fixtures/tmuxp/sleep.yaml

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 1 pane, even-vertical❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0: 1 pane, even-vertical❯ ./manage.py runserver
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, appended: 1 pane, even-vertical❯ echo "window in the history!"
no layout set
1:suppressed
Window 1, suppressed: 1 pane, even-vertical❯ echo "window not in the history!"
no layout set
2:default
Window 2, default: 1 pane, even-vertical❯ echo "session in the history!"
no layout set
3:mixed
Window 3, mixed: 3 panes, even-vertical❯ echo "command in the history!"❯ echo "command not in the history!"❯ echo "window in the history!"
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)

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
Window 0, zero: 1 pane, even-vertical❯ echo "this window's index will be zero"
no layout set
1:one
Window 1, one: 1 pane, even-vertical❯ echo "this window's index will be one"
no layout set
5:five
Window 5, five: 1 pane, even-vertical❯ echo "this window's index will be five"
no layout set

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

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

Loaded by:

  • EveryTmuxpExampleParses: Parses every fixture in the directory with parse_tmuxp, which the load command calls. (examples/workspace/tests/tmuxp_test.cpp; loaded by the library in a test; the command is not run)
Esc

Type to search.

Reference previewOpen reference