Example Configurations¶
Short hand / inline style¶
tmuxp has a short-hand syntax to for those who wish to keep their configs punctual.
YAML¶
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'
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"echo 'did you know'",
"echo 'you can inline'"
]
},
{
"shell_command": "echo 'single commands'"
},
"echo 'for panes'"
],
"window_name": "long form"
}
],
"session_name": "shorthands"
}
Blank panes¶
No need to repeat pwd or a dummy command. A null, 'blank',
'pane' are valid.
Note '' counts as an empty carriage return.
YAML¶
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
JSON¶
{
"windows": [
{
"panes": [
null,
"pane",
"blank"
],
"window_name": "Blank pane test"
},
{
"panes": [
null,
{
"shell_command": null
},
{
"shell_command": [
null
]
}
],
"window_name": "More blank panes"
},
{
"panes": [
"",
{
"shell_command": ""
},
{
"shell_command": [
""
]
}
],
"window_name": "Empty string (return)"
},
{
"panes": [
{
"focus": true
},
{
"start_directory": "/tmp"
}
],
"window_name": "Blank with options"
}
],
"session_name": "Blank pane test"
}
2 panes¶
YAML¶
session_name: 2-pane-vertical
windows:
- window_name: my test window
panes:
- echo hello
- echo hello
JSON¶
{
"windows": [
{
"panes": [
"echo hello",
"echo hello"
],
"window_name": "my test window"
}
],
"session_name": "2-pane-vertical"
}
3 panes¶
YAML¶
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
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"cd /var/log",
"ls -al | grep \\.log"
]
},
"echo hello",
"echo hello"
],
"shell_command_before": [
"cd ~/"
],
"layout": "main-vertical",
"window_name": "dev window"
}
],
"session_name": "3-panes"
}
4 panes¶
YAML¶
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
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"cd /var/log",
"ls -al | grep \\.log"
]
},
"echo hello",
"echo hello",
"echo hello"
],
"shell_command_before": [
"cd ~/"
],
"layout": "tiled",
"window_name": "dev window"
}
],
"session_name": "4-pane-split"
}
Start Directory¶
Equivalent to tmux new-window -c <start-directory>.
YAML¶
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 config's dir
start_directory: ./
panes:
- shell_command:
- echo '\033c
- ./ is relative to config file location
- ../ will be parent of config file
- ./test will be \"test\" dir inside dir of config file'
- shell_command:
- echo '\033c
- This way you can load up workspaces from projects and maintain
- relative paths.'
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"echo \"\\033c",
"it trickles down from session-level\""
]
},
"echo hello"
],
"window_name": "should be /var/"
},
{
"panes": [
{
"shell_command": [
"echo '\\033c",
"window start_directory concatenates to session start_directory",
"if it is not absolute'"
]
},
"echo hello"
],
"start_directory": "log",
"window_name": "should be /var/log"
},
{
"panes": [
{
"shell_command": [
"echo \\\\033c ~ has precedence. note: remember to quote ~ in YAML"
]
},
"echo hello"
],
"start_directory": "~",
"window_name": "should be ~"
},
{
"panes": [
"echo '\\033c absolute paths also have precedence.'",
"echo hello"
],
"start_directory": "/bin",
"window_name": "should be /bin"
},
{
"panes": [
{
"shell_command": [
"echo '\\033c",
"./ is relative to config file location",
"../ will be parent of config file",
"./test will be \\\"test\\\" dir inside dir of config file'"
]
},
{
"shell_command": [
"echo '\\033c",
"This way you can load up workspaces from projects and maintain",
"relative paths.'"
]
}
],
"start_directory": "./",
"window_name": "should be config's dir"
}
],
"session_name": "start directory",
"start_directory": "/var/"
}
Environment variable replacing¶
tmuxp will replace environment variables wrapped in curly brackets for values of these settings:
start_directorybefore_scriptsession_namewindow_nameshell_command_beforeglobal_optionsoptionsin session scope and window scope
tmuxp replaces these variables before-hand with variables in the
terminal tmuxp invokes in.
In this case of this example, assuming the username “user”:
$ MY_ENV_VAR=foo tmuxp load examples/env-variables.yaml
and your session name will be session - user (foo).
Shell variables in shell_command do not support this type of
concatenation. shell_command and shell_command_before both
support normal shell variables, since they are sent into panes
automatically via send-key in tmux(1). See ls $PWD in
example.
If you have a special case and would like to see behavior changed, please make a ticket on the issue tracker.
YAML¶
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
JSON¶
{
"before_script": "${MY_ENV_VAR}/test3.sh",
"windows": [
{
"panes": [
{
"shell_command": [
"tail -F /var/log/syslog"
]
}
],
"start_directory": "/var/log",
"window_name": "editor"
},
{
"panes": [
{
"shell_command": [
"htop",
"ls $PWD"
]
}
],
"window_name": "logging for ${USER}",
"options": {
"automatic-rename": true
}
}
],
"shell_command_before": "echo ${PWD}",
"start_directory": "${PWD}/test",
"session_name": "session - ${USER} (${MY_ENV_VAR})"
}
Environment variables¶
tmuxp will set session environment variables.
YAML¶
session_name: Environment variables test
environment:
EDITOR: /usr/bin/vim
HOME: /tmp/hm
windows:
# Emptiness will simply open a blank pane, if no shell_command_before.
# All these are equivalent
- window_name: Blank pane test
panes:
-
JSON¶
{
"environment": {
"EDITOR": "/usr/bin/vim",
"HOME": "/tmp/hm",
},
"windows": [
{
"panes": [
null,
],
"window_name": "Blank pane test"
},
],
"session_name": "Environment variables test"
}
Focusing¶
tmuxp allows focus: true for assuring windows and panes are attached /
selected upon loading.
YAML¶
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
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"echo hello",
"echo 'this pane should be selected on load'"
],
"focus": true
},
{
"shell_command": [
"cd /var/log",
"echo hello"
]
}
],
"window_name": "attached window on load",
"focus": true
},
{
"panes": [
"pane",
{
"shell_command": [
"echo 'this pane should be focused, when window switched to first time'"
],
"focus": true
},
"pane"
],
"shell_command_before": "cd /var/www",
"window_name": "second window"
}
],
"session_name": "focus window and pane when loading sessions"
}
Terminal History¶
tmuxp allows suppress_history: false to override the default command /
suppression when building the workspace.
This will add the shell_command to the bash history in the pane.
YAML¶
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!"
JSON¶
{
"windows": [
{
"panes": [
"echo 'window in the history!'"
],
"focus": true,
"suppress_history": false,
"window_name": "appended"
},
{
"panes": [
"echo 'window not in the history!'"
],
"suppress_history": true,
"window_name": "suppressed"
},
{
"panes": [
"echo 'session in the history!'"
],
"window_name": "default"
},
{
"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 not in the history!'"
}
],
"suppress_history": true,
"window_name": "mixed"
}
],
"suppress_history": false,
"session_name": "suppress"
}
Window Index¶
You can specify a window’s index using the window_index property. Windows
without window_index will use the lowest available window index.
YAML¶
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"
JSON¶
{
"windows": [
{
"panes": [
"echo \"this window's index will be zero\""
],
"window_name": "zero"
},
{
"panes": [
"echo \"this window's index will be five\""
],
"window_index": 5,
"window_name": "five"
},
{
"panes": [
"echo \"this window's index will be one\""
],
"window_name": "one"
}
],
"session_name": "Window index example"
}
Set tmux options¶
Works with global (server-wide) options, session options and window options.
Including automatic-rename, default-shell,
default-command, etc.
YAML¶
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"
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"man echo"
],
"start_directory": "~"
},
{
"shell_command": [
"echo \"hey\""
]
},
{
"shell_command": [
"echo \"moo\""
]
}
],
"layout": "main-horizontal",
"options": {
"automatic-rename": true
}
}
],
"session_name": "test window options",
"start_directory": "~",
"global_options": {
"default-shell": "/bin/sh",
"default-command": "/bin/sh"
},
"options": {
"main-pane-height": "${MAIN_PANE_HEIGHT}"
}
}
Set window options after pane creation¶
Apply window options after panes have been created. Useful for
synchronize-panes option after executing individual commands in each
pane during creation.
YAML¶
session_name: 2-pane-synchronized
windows:
- window_name: Two synchronized panes
panes:
- ssh server1
- ssh server2
options_after:
synchronize-panes: on
JSON¶
{
"session_name": "2-pane-synchronized",
"windows": [
{
"window_name": "Two synchronized panes",
"panes": [
"ssh server1",
"ssh server2"
],
"options_after": {
"synchronize-panes": true
}
}
]
}
Main pane height¶
YAML¶
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
JSON¶
{
"windows": [
{
"panes": [
{
"shell_command": [
"top"
],
"start_directory": "~"
},
{
"shell_command": [
"echo \"hey\""
]
},
{
"shell_command": [
"echo \"moo\""
]
}
],
"layout": "main-horizontal",
"options": {
"main-pane-height": 30
},
"window_name": "editor"
}
],
"session_name": "main pane height",
"start_directory": "~"
}
Super-advanced dev environment¶
See also
tmuxp developer config in the Developing and Testing section.
YAML¶
session_name: tmuxp
start_directory: ./ # load session relative to config location (project root).
before_script: ./.tmuxp-before-script.sh
shell_command_before:
- '[ -f .venv/bin/activate ] && source .venv/bin/activate && reset'
windows:
- window_name: tmuxp
focus: True
layout: main-horizontal
options:
main-pane-height: 35
panes:
- focus: true
- pane
- make watch_test
- window_name: docs
layout: main-horizontal
options:
main-pane-height: 35
start_directory: docs/
panes:
- focus: true
- pane
- make serve
- make SPHINXBUILD='poetry run sphinx-build' watch
JSON¶
{
"session_name": "tmuxp",
"start_directory": "./",
"before_script": "./.tmuxp-before-script.sh",
"shell_command_before": [
"[ -f .venv/bin/activate ] && source .venv/bin/activate && reset"
],
"windows": [
{
"window_name": "tmuxp",
"focus": true,
"layout": "main-horizontal",
"options": {
"main-pane-height": 35
},
"panes": [
{
"focus": true
},
"pane",
"make watch_test"
]
},
{
"window_name": "docs",
"layout": "main-horizontal",
"options": {
"main-pane-height": 35
},
"start_directory": "docs/",
"panes": [
{
"focus": true
},
"pane",
"make serve",
"make SPHINXBUILD='poetry run sphinx-build' watch"
]
}
]
}
Bootstrap project before launch¶
You can use before_script to run a script before the tmux session
starts building. This can be used to start a script to create a virtualenv
or download a virtualenv/rbenv/package.json’s dependency files before
tmuxp even begins building the session.
It works by using the Exit Status code returned by a script. Your script can be any type, including bash, python, ruby, etc.
A successful script will exit with a status of 0.
Important: the script file must be chmod executable +x or 755.
Run a python script (and check for it’s return code), the script is relative to the ``.tmuxp.yaml``’s root (Windows and panes omitted in this example):
session_name: my session
before_script: ./bootstrap.py
# ... the rest of your config
{
"session_name": "my session",
"before_script": "./bootstrap.py"
}
Run a shell script + check for return code on an absolute path. (Windows and panes omitted in this example)
session_name: another example
before_script: /absolute/path/this.sh # abs path to shell script
# ... the rest of your config
{
"session_name": "my session",
"before_script": "/absolute/path/this.sh"
}
Per-project tmux config¶
You can load your software project in tmux by placing a .tmuxp.yaml or
.tmuxp.json in the project’s config and loading it.
tmuxp supports loading configs via absolute filename with tmuxp load
and via $ tmuxp load . if config is in directory.
$ tmuxp load ~/workspaces/myproject.yaml
See examples of tmuxp in the wild. Have a project config to show off?
Edit this page.
- https://github.com/tony/dockerfiles/blob/master/.tmuxp.yaml
- https://github.com/tony/vcspull/blob/master/.tmuxp.yaml
- https://github.com/tony/sphinxcontrib-github/blob/master/.tmuxp.yaml
You can use start_directory: ./ to make the directories relative to
the config file / project root.
Bonus: pipenv auto-bootstrapping¶
New in version 1.3.4: before_script CWD’s into the root (session)-level
start_directory.
If you use pipenv / poetry, you can use a script like this to ensure your packages are installed:
# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
windows:
- window_name: django project
focus: true
panes:
- blank
- pipenv run ./manage.py runserver
You can also source yourself into the virtual environment using
shell_command_before:
# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
shell_command_before:
- '[ -d `pipenv --venv` ] && source `pipenv --venv`/bin/activate && reset'
windows:
- window_name: django project
focus: true
panes:
- blank
- ./manage.py runserver
Kung fu¶
Note
tmuxp sessions can be scripted in python. The first way is to use the
ORM in the API Reference. The second is to pass a dict into
WorkspaceBuilder with a correct schema.
See: tmuxp.config.validate_schema().
Add yours? Submit a pull request to the github site!
