# tmuxinator

> Ruby CLI that creates and starts tmux sessions from YAML project files defining windows, panes, layouts, root directories, and startup hooks.

Stars: 13.7k · Language: Ruby · License: MIT · Categories: Shell

- Repository: https://github.com/tmuxinator/tmuxinator
- Page: https://www.trmn.sh/tools/tmuxinator

## Install

- RubyGems: `gem install tmuxinator`
- Homebrew: `brew install tmuxinator`

## Overview

tmuxinator is a session manager for tmux, written in Ruby. Each project is described in a YAML file that lists windows, panes, layouts, a root directory, and the commands to run in each. Starting the project builds the tmux session to match. Commands are sent to the shell with tmux send-keys, as if typed, so a pane can run `ssh` to a remote host and then run further commands there.

Projects are managed with `tmuxinator new [project]`, `open`, and `edit`, which are aliased to `n`, `o`, and `e`. `new --local` stores the config as `.tmuxinator.yml` in the current directory instead of the default config location. `tmuxinator new [project] [session]` records the windows, layouts, panes, session options, and root of an existing tmux session into a new project file.

The config supports per-window roots and the standard tmux layouts or custom layout strings. It also supports named panes, pane titles (tmux 2.6 or later), `focused_pane`, `startup_window`, and `startup_pane`. Lifecycle hooks are available: `on_project_start`, `on_project_first_start`, `on_project_restart`, `on_project_exit`, and `on_project_stop`. `pre_window` runs setup commands such as `rbenv shell` in every window and pane. Other options include `attach: false`, `tmux_options` for a custom tmux.conf, `tmux_command` for wrappers such as byobu, and `socket_name`. Project files can use ERB templating. Completion scripts are provided for bash, zsh, and fish.

It is aimed at developers who regularly rebuild the same multi-window, multi-pane terminal layouts for projects, such as an editor, a server, and log tailing. The README assumes you already know tmux windows and panes. It recommends tmux 1.8 or later and says 2.5 is not supported.

### Installation

```bash
# via RubyGems
gem install tmuxinator
```

```bash
# via Homebrew
brew install tmuxinator
```

![tmuxinator starting a tmux session](https://media.trmn.sh/cached/91c8cfc932e7af4d505650e2db27826e1b637e921b06f56cb1253b91c03f86fe.gif)

## Alternatives

- [Pure](https://www.trmn.sh/tools/pure.md): ZSH prompt that shows git branch, dirty state, and async-checked unpushed/unpulled arrows, with exit-status coloring and command execution time. (Shell, 14.5k stars)
- [tpm](https://www.trmn.sh/tools/tpm.md): Tmux Plugin Manager: installs, updates, and removes tmux plugins from GitHub or other git repositories, configured via ~/.tmux.conf. (Shell, 15.1k stars)
- [genact](https://www.trmn.sh/tools/genact.md): Terminal program that prints fake activity output (compilers, builds, botnets, downloads) to look busy. Runs natively or in a browser via WebAssembly. (Rust, 12.2k stars)
- [direnv](https://www.trmn.sh/tools/direnv.md): Shell extension that automatically loads and unloads environment variables based on current directory (Go, 15.5k stars)
- [inshellisense](https://www.trmn.sh/tools/inshellisense.md): IDE-style autocomplete for shells, running as a terminal-native runtime for the withfig/autocomplete specs covering 600+ CLI tools on Windows, Linux, and macOS. (TypeScript, 10.7k stars)

---

Canonical: https://www.trmn.sh/tools/tmuxinator