Note

tmuxp is usable but still needs your help reporting errors, bugs and usability feedback. If you encounter an error, please post on the Issue tracker.

Examples

Short hand / inline

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:
      - pwd
      - pwd

JSON

{
  "windows": [
    {
      "panes": [
        "pwd", 
        "pwd"
      ], 
      "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
    - pwd
    - pwd

JSON

{
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "cd /var/log", 
            "ls -al | grep \\.log"
          ]
        }, 
        "pwd", 
        "pwd"
      ], 
      "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
    - pwd
    - pwd
    - pwd

JSON

{
  "windows": [
    {
      "panes": [
        {
          "shell_command": [
            "cd /var/log", 
            "ls -al | grep \\.log"
          ]
        }, 
        "pwd", 
        "pwd", 
        "pwd"
      ], 
      "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"
      - pwd
  - 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'
      - pwd
  - window_name: should be ~
    start_directory: '~'
    panes:
    - shell_command:
      - 'echo \\033c ~ has precedence. note: remember to quote ~ in YAML'
    - pwd
  - window_name: should be /proc
    start_directory: /proc
    panes:
    - echo '\033c absolute paths also have precedence.'
    - pwd
  - 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\""
          ]
        }, 
        "pwd"
      ], 
      "window_name": "should be /var/"
    }, 
    {
      "panes": [
        {
          "shell_command": [
            "echo '\\033c", 
            "window start_directory concatenates to session start_directory", 
            "if it is not absolute'"
          ]
        }, 
        "pwd"
      ], 
      "start_directory": "log", 
      "window_name": "should be /var/log"
    }, 
    {
      "panes": [
        {
          "shell_command": [
            "echo \\\\033c ~ has precedence. note: remember to quote ~ in YAML"
          ]
        }, 
        "pwd"
      ], 
      "start_directory": "~", 
      "window_name": "should be ~"
    }, 
    {
      "panes": [
        "echo '\\033c absolute paths also have precedence.'", 
        "pwd"
      ], 
      "start_directory": "/proc", 
      "window_name": "should be /proc"
    }, 
    {
      "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/"
}

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:
      - pwd
      - echo 'this pane should be selected on load'
      focus: true
    - shell_command:
      - cd /var/log
      - pwd
  - 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": [
            "pwd", 
            "echo 'this pane should be selected on load'"
          ], 
          "focus": true
        }, 
        {
          "shell_command": [
            "cd /var/log", 
            "pwd"
          ]
        }
      ], 
      "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"
}

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"
}

Automatic Rename

YAML

session_name: test window options
start_directory: '~'
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": "~"
}

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

YAML

session_name: tmuxp
start_directory: ./ # load session relative to config location (project root).
before_script: ./bootstrap_env.py # ./ to load relative to project root.
windows:
- window_name: tmuxp
  focus: True
  layout: main-horizontal
  options:
    main-pane-height: 35
  shell_command_before:
    - '[ -d .env -a -f .env/bin/activate ] && source .env/bin/activate'
  panes:
  - focus: true
  - pane 
  - sniffer
- window_name: docs
  layout: main-horizontal
  options:
    main-pane-height: 35
  start_directory: doc/
  shell_command_before: 
    - '[ -d ../.env -a -f ../.env/bin/activate ] && source ../.env/bin/activate'
  panes:
  - focus: true
  - pane
  - echo 'docs built to <http://0.0.0.0:8003/_build/html>'; python -m SimpleHTTPServer 8003
  - sniffer

JSON

{
  "before_script": "./bootstrap_env.py", 
  "windows": [
    {
      "panes": [
        {
          "focus": true
        }, 
        "pane", 
        "sniffer"
      ], 
      "options": {
        "main-pane-height": 35
      }, 
      "layout": "main-horizontal", 
      "shell_command_before": [
        "[ -d .env -a -f .env/bin/activate ] && source .env/bin/activate"
      ], 
      "focus": true, 
      "window_name": "tmuxp"
    }, 
    {
      "panes": [
        {
          "focus": true
        }, 
        "pane", 
        "echo 'docs built to <http://0.0.0.0:8003/_build/html>'; python -m SimpleHTTPServer 8003", 
        "sniffer"
      ], 
      "start_directory": "doc/", 
      "layout": "main-horizontal", 
      "shell_command_before": [
        "[ -d ../.env -a -f ../.env/bin/activate ] && source ../.env/bin/activate"
      ], 
      "options": {
        "main-pane-height": 35
      }, 
      "window_name": "docs"
    }
  ], 
  "session_name": "tmuxp", 
  "start_directory": "./"
}

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.

You can use start_directory: ./ to make the directories relative to the config file / project root.

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 tmuxp.WorkspaceBuilder with a correct schema. See: tmuxp.config.validate_schema().

Add yours? Submit a pull request to the github site!