Tmuxinator: the Ruby layer that turns a tmux session into a YAML file

gem install leaves shell completion unwritten

A distribution package manager may place the completion files where your shell finds them at startup. A `gem` install does not, and the difference is stated rather than glossed over: if you installed through Ruby's `gem`, you run these yourself.

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.bash -O /etc/bash_completion.d/tmuxinator.bash

For zsh:

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.zsh -O /usr/local/share/zsh/site-functions/_tmuxinator

And for fish:

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.fish -O ~/.config/fish/completions/tmuxinator.fish

The destination paths differ in kind, and that matters before you run anything. The bash path writes into `/etc/bash_completion.d/`, which is a system directory, so a user without write access there will get a permission error rather than a missing feature. The zsh path writes into `/usr/local/share/zsh/site-functions/`, also system-level, and the note adds that zsh completion files can be put in other locations in your `$fpath`, referring to the zsh manual for details. The fish path writes to `~/.config/fish/completions/tmuxinator.fish`, which is per user. Two of the three commands need elevated filesystem access, and none of them happen automatically on the gem path. Fetched from the `master` branch of the raw GitHub URL rather than from a versioned tag, so what lands on your system is whatever that branch holds at the moment you run it.

Homebrew is documented but advised against

Two install routes are given and one is quietly discouraged. The RubyGems route is `gem install tmuxinator`, and the Homebrew route is `brew install tmuxinator`. Between them sits the caveat that decides the choice for most people: some users have reported issues when installing via Homebrew, referenced as issue 841, so the RubyGems installation is preferred until these are resolved. A reader taking that at face value picks the gem. A reader who would rather not manage Ruby at all still has to know that the supported route is the one requiring a working Ruby installation, which is why the next paragraph then discusses system Ruby versions and version managers at length. The wording is careful: the preference is stated as conditional on those issues being unresolved, not as permanent. So the Homebrew path is presented as usable and unendorsed, and an adopter on macOS with Homebrew already in place will have to make that judgment rather than being told outright.

System Ruby is the reason version managers appear in the docs

Tmuxinator aims to be compatible with the currently maintained versions of Ruby. The snag is that some operating systems may provide an unsupported version of Ruby as their system ruby. The stated remedy is to use RVM or rbenv to install a supported Ruby version and to use that version's `gem` binary to install tmuxinator. That last clause is the part worth slowing down on: the fix is not only about having a newer Ruby, it is about invoking the specific `gem` belonging to that Ruby. A user on a distribution that ships an old system Ruby who types `gem install tmuxinator` unqualified may install into a Ruby the project does not target, and the resulting error would come from the interpreter rather than from tmuxinator. The document does not say how to check which Ruby your `gem` belongs to, so the verification step is left to the reader.

tmux 2.5 is excluded from an otherwise 1.8+ requirement

The tmux requirement reads as a version floor with one hole punched through it. The recommended version of tmux is 1.8 or later, with the exception of 2.5, which is not supported, pointing at issue 536 for details. For versions earlier than 1.8, the note is that your mileage may vary, with a pointer to the FAQ for any odd behaviour. So the supported set is not contiguous, and a reader sitting on 2.5 has to understand that installing the gem is not the problem and the tmux version is. Nothing here states a failure mode, an error message or a workaround; the issue link carries that detail instead. The FAQ is named as the place to look for any odd behaviour.

A dot in the project name breaks pane targeting

The most repeated warning in the file concerns project names. Dots cannot be used in project names, because tmux uses them internally to delimit between windows and panes, and tmuxinator uses the project name in combination with those indices to target the correct pane or window. The mechanism explains the consequence: tmux derives pane targets from a name that already contains its own delimiter, so the addressing becomes ambiguous and the wrong pane or window is addressed. The note appears in the section on creating projects and again at the top of the section on panes, which tells you the problem bites in two different places. A configuration that looks correct can still fail for this reason alone, and nothing in the generated YAML warns you, since the name is whatever you typed at the prompt.

Windows take panes as children, and per-window root wins

The windows option allows the specification of any number of tmux windows, each denoted by a YAML array entry followed by a name and a command to be run.

windows:
  - editor: vim

A named window key can be replaced by a null YAML value such as `null` or `~`, which causes the window to use its default name, usually the name of the user's shell. Panes are optional and are children of window entries, and unlike windows they do not need a name:

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

An optional root can be specified per window, and this takes precedence over the main root option. The layout setting gets handed down to tmux directly, so you can choose from the five standard layouts or specify your own. The file also flags a separate source of confusion: the indentation in these examples is deliberate, because YAML indentation rules can mislead, and a config that is not working as expected should be checked against indentation first.

The default config is mostly commented-out hooks

Run `tmuxinator new [project]` on a fresh project and the generated YAML opens with a name, a root and a set of commented-out options.

# ~/.tmuxinator/sample.yml

name: sample
root: ~/

# Optional tmux socket
# socket_name: foo

The lines shown after `root: ~/` are comments. The project hooks are each listed with the condition attached: `on_project_start` runs on project start always, `on_project_first_start` runs the first time only, `on_project_restart` runs on project start after the first time, `on_project_exit` runs on project exit when detaching from the tmux session, and `on_project_stop` runs on project stop. Above them sits a deprecation note that the pre and post options have been deprecated and will be replaced by project hooks, which is a warning that a config written against older syntax carries keys the project is moving away from.

An existing session can be reverse-engineered into a project

You do not have to author the YAML by hand, because a project can be created from a session tmux already has:

tmuxinator new [project] [session]

This records the windows, along with their specified layout, panes, tmux session options, and project root, basing the root on the tmux default-path of the specified tmux session, and writes them into a new tmuxinator project. That makes capture the practical starting point for anyone whose working layout has accumulated by hand and would be tedious to describe in YAML. Two caveats follow. Separately, `tmuxinator new --local [project]` stores the config in `.tmuxinator.yml` in the current working directory instead of the default project configuration file location such as `~/.config/tmuxinator`, which is what you want when the config should live in a repository next to the code.

Editorial conclusion

Use Tmuxinator if your tmux setup has grown past a couple of remembered keybindings and you want the session definition in a file you can commit and share. Skip it if you want a terminal emulator or anything that replaces tmux itself, because this is a management layer, not a multiplexer. Before adopting, confirm your tmux is 1.8 or later and not 2.5, decide between the RubyGems and Homebrew paths with the Homebrew caveat in mind, and budget for the completion files, which a gem install does not place for you.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tmuxinator/tmuxinator on GitHub