Tmuxinator: declarative tmux sessions from a YAML file

The problem Tmuxinator solves for tmux users

tmux itself has no memory of intent. You start a session, split a window, rename it, cd into a directory, run a server in one pane and a log tail in another, and then detach. Tomorrow you repeat all of it by hand, and the day after that you repeat it slightly differently. Tmuxinator exists to remove that repetition: the README describes it as a way to "Create and manage tmux sessions easily", and the mechanism is a per-project YAML file that records the session shape.

The audience is narrow and worth stating plainly. The README says a working knowledge of tmux is assumed, and that you should understand what windows and panes are before going further. This is not a tool that teaches tmux or hides it. It is a layer that types tmux commands for you, in the order and shape you declared. If you have never used tmux, the config file will read as a list of nouns you cannot yet picture.

What you get in return is a session you can rebuild with one command, checked into a repository next to the code it serves, and edited in your normal editor. That last point matters more than it sounds: because the project file is plain text, a layout change is a diff, not a sequence of keystrokes someone has to remember.

How a project file becomes a running session

The unit of work is a project, and a project is a YAML document. The default config the README shows has a name, a root directory, and a windows list. Each entry in that list is either a window name with a command, such as `server: bundle exec rails s`, or a window name with a nested layout and panes.

The nesting is where most of the expressiveness lives. A window can declare `layout: main-vertical`, list panes, and mark one pane as focused with `focused_pane: editor`. Panes can carry their own command, as in `editor: vim`. Indices are zero-based and, per the README comment, automatically adjusted to your pane-base-index, so the file does not have to hard-code the tmux option you happen to run with.

Around the window list sit project hooks and session options. The README lists `on_project_start`, `on_project_first_start`, `on_project_restart`, `on_project_exit` and `on_project_stop`, and notes that the older `pre` and `post` options are deprecated in favour of these hooks. Session-level knobs include `socket_name`, `tmux_options` for passing flags such as a different tmux.conf, `tmux_command` for wrappers like byobu, `startup_window` and `startup_pane`, and `attach`, which defaults to true. Pane titles are off by default and can be turned on with `enable_pane_titles`, positioned with `pane_title_position` (bottom, top, or the quoted string "off"), and formatted with `pane_title_format`.

There is also a reverse path. The README documents `tmuxinator new [project] [session]`, which creates a project from an existing tmux session and records its windows. That is the practical way to capture a layout you built by hand before you commit it to a file.

Installing Tmuxinator and creating a first project

The README gives two installation routes. RubyGems is listed first, and the README explicitly calls it the preferred one: it notes that some users have reported issues with the Homebrew install and says the RubyGems installation is preferred until those are resolved. Before you install, check your Ruby. Tmuxinator aims to be compatible with the currently maintained Ruby versions, and the README warns that some operating systems ship an unsupported version as their system Ruby, in which case you should install a supported one with RVM or rbenv and use that version's gem binary.

gem install tmuxinator

On the tmux side, the README recommends tmux 1.8 or later, with one exception: version 2.5 is not supported, and it links issue 536 for the details. Earlier versions are described as variable.

Once installed, create a project. The command opens your default editor, which comes from $EDITOR; the README suggests checking it with `echo $EDITOR` and setting it in your shell profile if you want something other than the default.

tmuxinator new [project]

If this is a new project you get the default config the README prints, with a sample window named editor that uses `layout: main-vertical` and two panes, one running vim and one named guard, plus commented-out options for hooks, startup window and pane, attach behaviour and pane titles. Replace the sample windows with your own. To keep the file beside the code instead of in the default project location, use the local form, which writes `.tmuxinator.yml` into the current working directory:

tmuxinator new --local [project]

Two aliases are worth knowing: `new`, `open` and `edit` are aliased to `n`, `o` and `e`, and `open` will create a config while `edit` only opens an existing one. One constraint from the README: dots cannot appear in project names, because tmux uses them internally to delimit windows and panes. Shell completion is not automatic for gem installs; the README provides wget commands that place completion files for bash, zsh and fish in the paths those shells load from, and notes that a distribution package manager may already have done it.

Where Tmuxinator stops being the right tool

The dependency on Ruby is the first boundary. If the machine cannot run a maintained Ruby and you cannot install one, the gem route is closed, and the README's own note about Homebrew issues means the alternative route carries known friction. This is not a single static binary you can drop onto a locked-down host.

The tmux version floor is the second. The README recommends 1.8 or later and rules out 2.5 entirely. If your environment pins an older tmux, the documentation offers no support commitment, only "your mileage may vary".

The third boundary is conceptual rather than technical. Tmuxinator does not manage tmux for you in any ongoing sense. It builds a session from a declaration and then steps back. If what you actually want is a terminal emulator, or a multiplexer replacement, this is the wrong layer entirely; the configuration file assumes tmux is already there and already understood. The README also does not document rollback for a partially started session, so if a pane command fails midway through startup, the documented material does not describe a recovery path. Treat a broken project file as a broken session and fix the file.

Finally, the project file is a shared artifact. Because it lives in the repository, a change to the layout affects everyone who runs it, including people on different Ruby versions and different pane-base-index settings. The README's note that indices are adjusted automatically softens that, but the rest of the file is literal.

Tmuxinator compared with tmuxp and plain tmux

The obvious comparison is plain tmux, and the difference is not capability but persistence of intent. tmux gives you commands; Tmuxinator gives you a file that replays those commands. If your sessions are one-off and you never repeat a layout, the file is overhead. If you start the same five-pane setup every morning, the file is the whole point.

The closer alternative is tmuxp, which occupies the same niche from a different runtime. The practical difference is the language you already have installed: Tmuxinator is a Ruby gem, so it needs a supported Ruby and installs through `gem install tmuxinator`, while tmuxp is a Python tool and fits a Python-managed environment. Both express sessions as declarative configuration rather than as a sequence of shell commands, so the migration cost between them is mostly in the config schema, not in the mental model. If your team already standardises on Python tooling, tmuxp removes the Ruby prerequisite. If your team already has Ruby, Tmuxinator's hook set and its `new [project] [session]` capture path are the reason to stay.

A third option appears in the search data: sesh. It is a different kind of tool, aimed at session switching rather than at declaring and rebuilding a fixed layout, so it does not replace Tmuxinator for reproducible project sessions. The honest summary is that Tmuxinator and tmuxp are the two direct choices, and the decision is usually made by which runtime you can guarantee on the machines that need it.

Maintenance, licence and upgrade cost

Tmuxinator is not archived, and the last push to the default branch was on 2026-07-10. Releases are recent and versioned: v3.4.1 on 2026-07-03, v3.4.0 on 2026-05-23, and v3.3.8 on 2026-03-26. The repository carries a CHANGELOG.md, which is where upgrade notes belong, and the README notes that the `pre` and `post` options are deprecated in favour of project hooks. That deprecation is the concrete upgrade cost to plan for: a config still using `pre` or `post` is on a path the README says will be replaced, so converting to `on_project_start` and the other hooks is the migration to schedule.

The licence is MIT. In plain terms, that is a permissive licence that allows use, modification and redistribution provided the copyright notice and licence text are kept. It is not a copyleft licence, so it does not require you to publish changes you make. This is a description of the licence identifier, not legal advice; if your organisation has rules about which licences it accepts, check the LICENSE file in the repository against them.

Operationally, the cost is the Ruby runtime. Because Tmuxinator targets the currently maintained Ruby versions, an upgrade of Ruby on a host can affect it, and the README's advice to use RVM or rbenv rather than a system Ruby is also the advice that keeps this manageable. There is no compiled artifact to rebuild.

Editorial conclusion

Adopt Tmuxinator if you already live in tmux and keep retyping the same window and pane layout, and if a maintained Ruby is available on the machine. Do not adopt it if you want a terminal emulator, a tmux replacement, or a tool that manages sessions without a Ruby runtime; tmuxp is the closer fit for a Python-only stack. Before committing, verify which Ruby your system provides and install a supported one through RVM or rbenv if needed, confirm your tmux version is 1.8 or later and not 2.5, and check where the config lands (the default location or a local .tmuxinator.yml).

Frequently asked questions

Official sources

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