Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Manage complex tmux sessions easily

Subscribe to updates I use tmuxinator

Statistics on tmuxinator

Number of watchers on Github 7617
Number of open issues 97
Average time to close an issue 18 days
Main language Ruby
Average time to merge a PR 14 days
Open pull requests 45+
Closed pull requests 28+
Last commit over 1 year ago
Repo Created almost 9 years ago
Repo Last Updated over 1 year ago
Size 707 KB
Organization / Authortmuxinator
Latest Releasev0.10.1
Page Updated
Do you use tmuxinator? Leave a review!
View open issues (97)
View tmuxinator activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating tmuxinator for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Gem Version Build Status Coverage Status Code Climate Dependency Status Gitter

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:

echo $EDITOR

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:

export EDITOR='vim'


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.


If you use a base-index other than the default, please be sure to also set the pane-base-index

set-window-option -g pane-base-index 1


Download the appropriate completion file from the repo and source the file. The following are example where the completion file has been downloaded into ~/.bin.


Add the following to your ~/.bashrc:

source ~/.bin/tmuxinator.bash


Add the following to your ~/.zshrc:

source ~/.bin/tmuxinator.zsh


Move to your completions folder:

cp ~/.bin/ ~/.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 o,open, e, edit and n. 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

  - editor:
      layout: main-vertical
        - 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.

  - editor: vim

Window specific root

An optional root option can be specified per window:

name: test
root: ~/projects/company

  - small_project:
      root: ~/projects/company/small_project
        - 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.

  - editor:
      layout: main-vertical
        - vim
        - guard

The layout setting gets handed down to tmux directly, so you can choose from one of the five standard layouts or specify your own.

Interpreter Managers & Environment Variables

To use tmuxinator with rbenv, RVM, NVM etc, use the pre_window option.

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 attach option.

attach: false

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_start: tmux -CC attach

Passing directly to send-keys

tmuxinator passes commands directly to send keys. This differs from simply chaining commands together using && or ;, 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: ~/

  - stats:
    - ssh
    - tail -f /var/log/stats.log
  - logs:
      layout: main-vertical
        - logs:
          - ssh
          - 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 @args.


$ tmuxinator start project foo
# ~/.tmuxinator/project.yml

name: project
root: ~/<%= @args[0] %>


You can also pass key-value pairs using the format key=value. These will be available in a hash named @settings.


$ 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 s.

tmuxinator start [project] -n [name]

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.


The shell completion files also include a shorthand alias for tmuxinator that can be used in place of the full name.

mux [command]

Other Commands

Copy an existing project. Aliased to c and cp

tmuxinator copy [existing] [new]

List all the projects you have configured. Aliased to l and ls

tmuxinator list

Remove a project. Aliased to rm

tmuxinator delete [project]

Remove all tmuxinator configs, aliases and scripts. Aliased to i

tmuxinator implode

Examines your environment and identifies problems with your configuration

tmuxinator doctor

Shows tmuxinator's help. Aliased to h

tmuxinator help

Shows the shell commands that get executed for a project

tmuxinator debug [project]

Shows tmuxinator's version.

tmuxinator version

Project Configuration Location

Using environment variables, it's possible to house project configuration files in non-standard directories. (See PR #511.)

Tmuxinator will attempt to use the following environment variables (in this order) when creating or searching for existing project configuration files:

  • $XDG_CONFIG_HOME/tmuxinator
  • ~/.tmuxinator

This behavior is opt-in. If you do nothing, Tmuxinator will continue to use ~/.tmuxinator when searching for existing project configuration files or creating new project configuration files.


Window names are not displaying properly?

Add export DISABLE_AUTO_TITLE=true to your .zshrc or .bashrc


To contribute, please read the contributing guide.


Copyright (c) 2010-2018 Allen Bargi, Christopher Chow. See LICENSE for further details.

tmuxinator open issues Ask a question     (View All Issues)
  • almost 3 years Can not create more than two panes in a window. It results in parse error.
  • almost 3 years tmuxinator and closing session
  • almost 3 years tmuxinator start project --windows window1 (or --panes window1.pane1) (or --windows window1,window2)
  • almost 3 years Tmuxinator 1st pane in 1st window does not receive commands
  • almost 3 years tmuxinator replay-pane -t ''
  • almost 3 years tmuxinator local -f filename.yml
  • almost 3 years tmux local debug
  • almost 3 years default values for @settings params
  • almost 3 years Tmuxinator doesn't run commands in tmux windows
  • almost 3 years tmuxinator config files in a different location
  • almost 3 years Replace screenshot with a gif in readme
  • almost 3 years Remove Object#blank? monkey patch
  • about 3 years Move validation functionality out of Tmuxinator::Config
  • about 3 years How to give focus to a particular pane/window
  • about 3 years Make synchronize pane default occur after startup commands have run
  • about 3 years .tmuxinator in repository root causes test failures
  • about 3 years Documentation for pane startup commands
  • about 3 years Consider requiring --local option when using `tmuxinator start` to start a local project
  • about 3 years Local config files use global path
  • about 3 years Add `tmuxinator new --local` entry to README
  • about 3 years `.tmuxinator.yml` in ./ overrides mux basic functionality
  • over 3 years Introduce Analytics Module
  • over 3 years Improve wemux support and clean up code
  • over 3 years Aliases are not listed in help menu
  • over 3 years Deprecation warnings in Project may present whitespace issues
  • over 3 years Resolve window/root relative to project root
  • over 3 years Ubuntu 16.04 package incorectly places the zsh completion file
  • over 3 years Better validation/error handling when Tmux is not installed
  • over 3 years tmux socket permission problem when using with wemux
  • over 3 years Feature Request: Custom [default].yml
tmuxinator open pull requests (View All Pulls)
  • Fix issue with creating panes with custom layout
  • Adds a default argument for a --default [filename].yml to be used as the
  • Minor correction in README
  • Add delete multiple projects feature
  • Use SHELL from env
  • Generate project file from tmux session
  • Synchronize panes support.
  • Add Stop Command
  • Use `tmux -V` command for checking tmux existence
  • introduce Contributor Covenant
  • Fix spacing in command list and add edit command to command list
  • Config.root refactoring
  • Resolve window root relative to project root
  • Fix for windows without panes
  • Generate project file from tmux session [reopened]
  • [WIP] Add command to append project to session
  • Add support for window synchronization.
  • Replace mux symlink with alias
  • Redirect stderr to /dev/null when listing tmux sessions
  • Replace instances of File.exists? (deprecated) with File.exist?
  • Only enable Synchronize panes after the commands have run
  • Fix wemux support
  • 385 introduce tmux validator
  • Test tmux versions 2.2 and 2.3
  • Support specified config directory and XDG Base Dirs Spec
  • Add ability for pre_window commands to parse yaml arrays (as well as strings)
  • Updated details on supported tmux versions
  • Inform user about 's' alias of start command
  • Add tmuxinator project hooks
  • Support specified config directory and XDG Base Dirs Spec (redux)
  • Attempt at salvaging PR #479
  • First pass at some basic integration tests
  • skips testing creation of a project when run within a tmux session
  • Issue 524 update ruby versions
  • Issue/520 config parse error message
  • Allow YAML aliases to work
  • Add Support for Pane Title
  • 575-format-deprecation-messages - use common formatting in deprecatio…
  • A more precise pre/post deprecation warning
  • Remove confusing README section on base indexes
  • Use correct tmux socket in tmux_has_session
  • Set pane name when hash is passed to panes config
  • fix default path for tmux master
  • Add CodeTriage badge to tmuxinator/tmuxinator
  • Fix error when using wemux instead of tmux
tmuxinator questions on Stackoverflow (View All Questions)
  • Using tmuxinator to open a dynamic number of windows
  • horizontal pane inside vertical pane with tmuxinator
  • tmuxinator initialize pane with multiple commands
  • How to create an unnamed window with tmuxinator?
  • Tmuxinator unable to parse config file
  • Inheritance in Tmuxinator configuration files
  • Send tmux command to tmuxinator
  • Is it possible to specify multiple commands in `tmuxinator`'s `pre_window`?
  • Is it possible to ssh 2 levels deep in tmux (tmuxinator) init script?
  • store tmuxinator config in project repository
  • How to split two vertical pane inside a horizontal pane in tmux using tmuxinator
  • How to save tmux session to tmuxinator project?
  • Autostart a Tmuxinator project on bootup under Ubuntu
  • Multiple tabs with tmux / tmuxinator and iTerm2
  • Tmuxinator Panes Code Won't Work
  • tmuxinator specify custom project config file
  • How to use multiple rvm gemsets in single tmuxinator session
  • Specify pane percentage in tmuxinator project
  • start a tmuxinator session on login
tmuxinator list of languages used
tmuxinator latest release notes
  • Handle emojis in project names (#564)
  • Fix remaining sites where the base-index option (for windows) was incorrectly used in place of the pane-base-index option.
  • Treat 'tmux master' as an arbitrarily high version and display a deprecation warning for unsupported tmux versions (#524, #570)
  • Add tmux 2.4, 2.5, and 2.6 to the TravisCI test matrix
  • Updates rubocop to resolve security vulnerability


  • Fix a bug causing the user's global pane-base-index setting not to be respected
  • Remove Object#blank? monkey patch (#458)
  • Add Project Configuration Location entry to README (#360, #534)
  • Attach original exception message to exception re-raised by Project::load
  • Remove unused attr_readers from Tmuxinator::Window
  • Add ability for pre_window commands to parse yaml arrays
  • Refactor Tmuxinator::Config by extracting a Tmuxinator::Doctor class (#457)
  • Fix a bug where startup_window and startup_pane were not respected if running tmuxinator from within an existing tmux session (#537)
  • Fix a bug causing the pane-base-index option to override base-index


  • Removed support for Ruby 1.9.3, 2.0, & 2.1
  • Move gem dependencies from Gemfile to tmuxinator.gemspec
  • Add tmux 2.2 and 2.3 the TravisCI test matrix
  • Fix typos
  • Support user-specified and XDG Base Dirs configuration directories

New Features

  • add on_project_start, on_project_first_start, on_project_restart, on_project_exit and on_project_stop hooks for project


  • Temporarily hiding Shorthand entry in to prevent new bug reports about the mux symlink being broken
  • Use alias (bash, zsh) and abbr (fish) instead of a symlink to hash mux. #401
  • replace instances of File.exists? (deprecated) with File.exist?
  • Refactor Config.root

New features

  • Allow mulitple panes to be defined using yaml hash or array #266, #406
  • Add startup_pane #380
  • Add synchronizations panes support #97
  • Add before and after options to synchronization functionality
  • Add deprecation warning if synchronize: true or before is used


  • Supress tmux ls non-zero exit status/message when no sessions exist (#414)
  • Will no longer crash when no panes are specified in a window
  • Locking activesupport at < 5.0.0 to prevent broken builds on Ruby < 2.2.3
  • Fixed whitespace issues in help
Other projects in Ruby