tmux workspace manager, forged in Go.
Session manager for tmux. Load, freeze, and convert tmux sessions through YAML/JSON configuration files. Powered by libtmux for Go.
Explore tmux layout / workspace possibilities
session_name: shorthandswindows: - 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'" ] } ]}session_name: 2-pane-verticalwindows: - 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" ] } ]}session_name: 3-paneswindows: - 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" ] } ]}session_name: 4-pane-splitwindows: - 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" ] } ]}session_name: main-pane-heightstart_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" } ]}session_name: nativestart_directory: .environment: {SESSION_VALUE: session}windows:- window_name: development window_index: 3 layout: even-horizontal environment: {WINDOW_VALUE: window} panes: - start_directory: one shell_command: 'printf "%s:%s:%s" "$SESSION_VALUE" "$WINDOW_VALUE" "$PANE_VALUE" > result' - start_directory: two environment: {PANE_VALUE: pane} shell_command: 'printf "%s:%s:%s" "$SESSION_VALUE" "$WINDOW_VALUE" "$PANE_VALUE" > result'- window_name: second focus: true panes: [blank]{ "session_name": "native", "start_directory": ".", "environment": { "SESSION_VALUE": "session" }, "windows": [ { "window_name": "development", "window_index": 3, "layout": "even-horizontal", "environment": { "WINDOW_VALUE": "window" }, "panes": [ { "start_directory": "one", "shell_command": "printf \"%s:%s:%s\" \"$SESSION_VALUE\" \"$WINDOW_VALUE\" \"$PANE_VALUE\" > result" }, { "start_directory": "two", "environment": { "PANE_VALUE": "pane" }, "shell_command": "printf \"%s:%s:%s\" \"$SESSION_VALUE\" \"$WINDOW_VALUE\" \"$PANE_VALUE\" > result" } ] }, { "window_name": "second", "focus": true, "panes": [ "blank" ] } ]}session_name: start directorystart_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.'" ] } ] } ]}session_name: 2-pane-synchronizedwindows: - 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" } } ]}session_name: Blank pane testwindows: # 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" } ] } ]}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" ] } ] } ]}session_name: focuswindows: - 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" ] } ]}session_name: main-pane-heightstart_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" } ]}session_name: My tmux sessionwindows: - panes: -{ "session_name": "My tmux session", "windows": [ { "panes": [ null ] } ]}session_name: test window optionsstart_directory: "~"global_options: default-shell: /bin/sh default-command: /bin/shoptions: main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variableswindows: - 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\"" ] } ] } ]}session_name: Pane shell examplewindows: - 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" } ] } ]}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 } ] } ] } ]}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 } ] } ]}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\"" } ] } ] } ]}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\"" } ] } ] } ]}session_name: virtualenvshell_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: 1windows: - 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" ] } ] } ]}session_name: suppresssuppress_history: falsewindows: - 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!\"" ] } ] } ]}session_name: Window index examplewindows: - 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\"" ] } ]}Install
Install the workspace package separately from the core library.
$ go install github.com/libtmux/libtmux-go/workspace/cmd/tmux-workspace@latestNeeds Go 1.26 or newer. Puts tmux-workspace in $(go env GOBIN), or in $(go env GOPATH)/bin when GOBIN is unset; rerunning it upgrades.
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¶
- Install the command and load a workspace.
- Configure windows and panes.
- 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.
Example workspaces
Each workspace below is a file that libtmux/libtmux-go
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: shorthandswindows: - 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.
Same file as tmuxp's examples/shorthands.yaml.
Source: workspace/testdata/tmuxp/shorthands.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; loaded by the library in a test; the command is not run)
Two panes
A window of two panes.
session_name: 2-pane-verticalwindows: - 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.
Same file as tmuxp's examples/2-pane-vertical.yaml.
Source: workspace/testdata/tmuxp/2-pane-vertical.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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-paneswindows: - 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.
Same file as tmuxp's examples/3-pane.yaml.
Source: workspace/testdata/tmuxp/3-pane.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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-splitwindows: - 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.
Same file as tmuxp's examples/4-pane.yaml.
Source: workspace/testdata/tmuxp/4-pane.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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: three panes
session_name: main-pane-heightstart_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.
Same file as tmuxp's examples/main-pane-height.yaml.
Source: workspace/testdata/tmuxp/main-pane-height.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; loaded by the library in a test; the command is not run)
Environment
environment sets variables for a session, a window or a pane.
Also shows: two panes, start directory
session_name: nativestart_directory: .environment: {SESSION_VALUE: session}windows:- window_name: development window_index: 3 layout: even-horizontal environment: {WINDOW_VALUE: window} panes: - start_directory: one shell_command: 'printf "%s:%s:%s" "$SESSION_VALUE" "$WINDOW_VALUE" "$PANE_VALUE" > result' - start_directory: two environment: {PANE_VALUE: pane} shell_command: 'printf "%s:%s:%s" "$SESSION_VALUE" "$WINDOW_VALUE" "$PANE_VALUE" > result'- window_name: second focus: true panes: [blank]{ "session_name": "native", "start_directory": ".", "environment": { "SESSION_VALUE": "session" }, "windows": [ { "window_name": "development", "window_index": 3, "layout": "even-horizontal", "environment": { "WINDOW_VALUE": "window" }, "panes": [ { "start_directory": "one", "shell_command": "printf \"%s:%s:%s\" \"$SESSION_VALUE\" \"$WINDOW_VALUE\" \"$PANE_VALUE\" > result" }, { "start_directory": "two", "environment": { "PANE_VALUE": "pane" }, "shell_command": "printf \"%s:%s:%s\" \"$SESSION_VALUE\" \"$WINDOW_VALUE\" \"$PANE_VALUE\" > result" } ] }, { "window_name": "second", "focus": true, "panes": [ "blank" ] } ]}Converted from the YAML; the tests load the YAML.
Source: workspace/internal/integration/cli_test.go
Loaded by:
-
TestLoadFreezeReloadAppendAndEnvironment: Runs load on a real tmux server and reads the files the panes write, which show the layered environment and each pane's directory. (workspace/internal/integration/cli_test.go; a test runs the command)
Start directory
start_directory chooses where a session, a window or a pane starts.
session_name: start directorystart_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.
Same file as tmuxp's examples/start-directory.yaml.
Source: workspace/testdata/tmuxp/start-directory.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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-synchronizedwindows: - 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.
Same file as tmuxp's examples/2-pane-synchronized.yaml.
Source: workspace/testdata/tmuxp/2-pane-synchronized.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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 testwindows: # 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.
Same file as tmuxp's examples/blank-panes.yaml.
Source: workspace/testdata/tmuxp/blank-panes.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; loaded by the library in a test; the command is not run)
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.
Same file as tmuxp's examples/env-variables.yaml.
Source: workspace/testdata/tmuxp/env-variables.yaml
Loaded by:
-
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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: focuswindows: - 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.
Same file as tmuxp's examples/focus-window-and-panes.yaml.
Source: workspace/testdata/tmuxp/focus-window-and-panes.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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-heightstart_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.
Same file as tmuxp's examples/main-pane-height-percentage.yaml.
Source: workspace/testdata/tmuxp/main-pane-height-percentage.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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 sessionwindows: - panes: -{ "session_name": "My tmux session", "windows": [ { "panes": [ null ] } ]}Converted from the YAML; the tests load the YAML.
Same file as tmuxp's examples/minimal.yaml.
Source: workspace/testdata/tmuxp/minimal.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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 optionsstart_directory: "~"global_options: default-shell: /bin/sh default-command: /bin/shoptions: main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variableswindows: - 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.
Same file as tmuxp's examples/options.yaml.
Source: workspace/testdata/tmuxp/options.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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 examplewindows: - 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.
Same file as tmuxp's examples/pane-shell.yaml.
Source: workspace/testdata/tmuxp/pane-shell.yaml
Loaded by:
-
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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.
Same file as tmuxp's examples/skip-send.yaml.
Source: workspace/testdata/tmuxp/skip-send.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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.
Same file as tmuxp's examples/skip-send-pane-level.yaml.
Source: workspace/testdata/tmuxp/skip-send-pane-level.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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.
Same file as tmuxp's examples/sleep.yaml.
Source: workspace/testdata/tmuxp/sleep.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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.
Same file as tmuxp's examples/sleep-pane-level.yaml.
Source: workspace/testdata/tmuxp/sleep-pane-level.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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: virtualenvshell_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: 1windows: - 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.
Same file as tmuxp's examples/sleep-virtualenv.yaml.
Source: workspace/testdata/tmuxp/sleep-virtualenv.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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: suppresssuppress_history: falsewindows: - 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.
Same file as tmuxp's examples/suppress-history.yaml.
Source: workspace/testdata/tmuxp/suppress-history.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; 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 examplewindows: - 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.
Same file as tmuxp's examples/window-index.yaml.
Source: workspace/testdata/tmuxp/window-index.yaml
Loaded by:
-
TestEveryTmuxpExampleParses: Parses every fixture in the directory with workspace.Parse. (workspace/workspace_test.go; parsed by the library in a test; the command is not run) -
TestEveryTmuxpExampleNormalizes: Reads every fixture in the directory with the loader the load command calls. (workspace/internal/cli/document_test.go; loaded by the library in a test; the command is not run)