Create and manage tmux sessions easily.
gem install tmuxinator
Editor and Shell
tmuxinator uses your shell's default editor for opening files. If you're not sure what that is type:
For me that produces "vim". If you want to change your default editor simply put a line in ~/.bashrc that changes it. Mine looks like this:
The recommended version of tmux to use is 1.8 or later, with the exception of 2.5, which is not supported (see issue 536 for details). Your mileage may vary for earlier versions. Refer to the FAQ for any odd behaviour.
Download the appropriate completion file from the repo and
source the file.
The following are example where the completion file has been downloaded into
Add the following to your
Add the following to your
tmuxinator.fish to your
cp ~/.bin/tmuxinator.fish ~/.config/fish/completions/
A working knowledge of tmux is assumed. You should understand what windows and panes are in tmux. If not please consult the man pages for tmux.
Create a project
Create or edit your projects with:
tmuxinator new [project]
For editing you can also use
tmuxinator open [project].
new is aliased to
e. Please note that dots can't be used in project
names as tmux uses them internally to delimit between windows and panes.
Your default editor (
$EDITOR) is used to open the file.
If this is a new project you will see this default config:
# ~/.tmuxinator/sample.yml name: sample root: ~/ # Optional. tmux socket # socket_name: foo # Note that the pre and post options have been deprecated and will be replaced by # project hooks. # Project hooks # Runs on project start, always # on_project_start: command # Run on project start, the first time # on_project_first_start: command # Run on project start, after the first time # on_project_restart: command # Run on project exit ( detaching from tmux session ) # on_project_exit: command # Run on project stop # on_project_stop: command # Runs in each window and pane before window/pane specific commands. Useful for setting up interpreter versions. # pre_window: rbenv shell 2.0.0-p247 # Pass command line options to tmux. Useful for specifying a different tmux.conf. # tmux_options: -f ~/.tmux.mac.conf # Change the command to call tmux. This can be used by derivatives/wrappers like byobu. # tmux_command: byobu # Specifies (by name or index) which window will be selected on project startup. If not set, the first window is used. # startup_window: logs windows: - editor: layout: main-vertical panes: - vim - guard - server: bundle exec rails s - logs: tail -f log/development.log
The windows option allows the specification of any number of tmux windows. Each window is denoted by a YAML array entry, followed by a name and command to be run.
windows: - editor: vim
Window specific root
An optional root option can be specified per window:
name: test root: ~/projects/company windows: - small_project: root: ~/projects/company/small_project panes: - start this - start that
This takes precedence over the main root option.
Note that if you wish to use panes, make sure that you do not have
. in your project name. tmux uses
. to delimit between window and pane indices,
and tmuxinator uses the project name in combination with these indices to target the correct pane or window.
Panes are optional and are children of window entries, but unlike windows, they do not need a name. In the following example, the
editor window has 2 panes, one running vim, the other guard.
windows: - editor: layout: main-vertical panes: - vim - guard
Please note the indentation here is deliberate. YAML's indentation rules can be confusing, so if your config isn't working as expected, please check the indentation. For a more detailed explanation of why YAML behaves this way, see this Stack Overflow question.
Interpreter Managers & Environment Variables
To use tmuxinator with rbenv, RVM, NVM etc, use the
pre_window: rbenv shell 2.0.0-p247
These command(s) will run before any subsequent commands in all panes and windows.
Custom session attachment
You can set tmuxinator to skip auto-attaching to the session by using the
If you want to attach to tmux in a non-standard way (e.g. for a program that makes use of tmux control mode like iTerm2), you can run arbitrary commands by using a project hook:
on_project_exit: tmux -CC attach
Passing directly to send-keys
tmuxinator passes commands directly to send keys. This differs from simply chaining commands together using
;, in that
tmux will directly send the commands to a shell as if you typed them in. This allows commands to be executed on a remote server over
SSH for example.
To support this both the window and pane options can take an array as an argument:
name: sample root: ~/ windows: - stats: - ssh email@example.com - tail -f /var/log/stats.log - logs: layout: main-vertical panes: - logs: - ssh firstname.lastname@example.org - cd /var/logs - tail -f development.log
Project files support ERB for reusability across environments. Eg:
root: <%= ENV["MY_CUSTOM_DIR"] %>
You can also pass arguments to your projects, and access them with ERB. Simple arguments are available in an array named
$ tmuxinator start project foo
# ~/.tmuxinator/project.yml name: project root: ~/<%= @args %> ...
You can also pass key-value pairs using the format
key=value. These will be available in a hash named
$ tmuxinator start project workspace=~/workspace/todo
# ~/.tmuxinator/project.yml name: project root: ~/<%= @settings["workspace"] %> ...
Starting a session
This will fire up tmux with all the tabs and panes you configured,
start is aliased to
tmuxinator start [project] -n [name] -p [project-config]
If you use the optional
[name] argument, it will start a new tmux session with the custom name provided. This is to enable reuse of a project without tmux session name collision.
If there is a
./.tmuxinator.yml file in the current working directory but not a named project file in
~/.tmuxinator, tmuxinator will use the local file. This is primarily intended to be used for sharing tmux configurations in complex development environments.
You can provide tmuxinator with a project config file using the optional
[project-config] argument (e.g.
-p path/to/my-project.yaml). This option will override a
[project] name (if provided) and a local tmuxinator file (if present).
The shell completion files also include a shorthand alias for tmuxinator that can be used in place of the full name.
Copy an existing project. Aliased to
tmuxinator copy [existing] [new]
List all the projects you have configured. Aliased to
Remove a project. Aliased to
tmuxinator delete [project]
Remove all tmuxinator configs, aliases and scripts. Aliased to
Examines your environment and identifies problems with your configuration
Shows tmuxinator's help. Aliased to
Shows the shell commands that get executed for a project
tmuxinator debug [project]
Shows tmuxinator's version.
Project Configuration Location
Using environment variables, it's possible to define which directory tmuxinator will use when creating or searching for project config files. (See PR #511.)
Tmuxinator will attempt to use the following locations (in this order) when creating or searching for existing project configuration files:
Window names are not displaying properly?
export DISABLE_AUTO_TITLE=true to your
To contribute, please read the contributing guide.
Copyright (c) 2010-2019 Allen Bargi, Christopher Chow. See LICENSE for further details.