tmuxinator
A Ruby command-line tool that defines tmux sessions, windows and panes in YAML config files.
- Stars
- 13.7k
- Forks
- 628
- Licence
- MIT
- Language
- Ruby
- Last update
- 27 days ago
- Type
- CLI
What it is
Tmuxinator lets you describe a tmux terminal setup (windows, panes, layouts, commands to run) in a YAML file and start it with one command. It is useful for people who regularly open the same multi-pane terminal workspace for a project. The README assumes you already know basic tmux concepts such as windows and panes.
- Create a project config with `tmuxinator new [project]` and define windows and panes
- Start a project session with a commands list, such as an editor in one pane and a Rails server in another
- Save an existing tmux session as a tmuxinator project with `tmuxinator new [project] [session]`
- Keep a project-specific config in the repo with `tmuxinator new --local [project]`
Great for
- Developers who restart the same project setup (editor, server, logs) every day
- People who already use tmux and want repeatable session layouts
- Teams that want to share a standard terminal setup via a project config file
Not ideal for
- People who do not use tmux; the README assumes working knowledge of tmux
- Users on very old tmux versions; the README says earlier versions may behave oddly and tmux 2.5 is not supported
How to get it
- 1
Install with a package manager
You'll need: Ruby (the README asks for a currently maintained Ruby version) · tmux (1.8 or later recommended; 2.5 not supported)
Install via RubyGems (preferred per README)
gem install tmuxinatorInstall via Homebrew (README notes reported issues)
brew install tmuxinator - 2
Run it
- Install tmux and Ruby, then run `gem install tmuxinator`
- Run `tmuxinator new sample` to create a project config and edit it in your $EDITOR
- Save the config and start the project with `tmuxinator start sample` or `tmuxinator sample`
- Optionally add shell completion files as described in the README's Completion section
- 3
Get the most out of it
- Use `tmuxinator new --local [project]` to keep the config inside a project directory
- Use `layout` and `focused_pane` options to control pane arrangement and focus
- Use project hooks such as on_project_start and on_project_stop for setup and teardown
- Use `startup_window` and `attach: false` to control which window opens and whether tmux attaches automatically
- Install the bash, zsh, or fish completion files to speed up typing commands
Downloads
Strengths
- Describes a whole terminal workspace in one readable YAML file
- Supports per-window root directories and tmux layouts
- Config can be stored locally in a project directory and shared
Trade-offs
- YAML indentation is strict and errors are easy to make, as the README notes
- The README says the Homebrew install has reported issues, so RubyGems is preferred
- Project names cannot contain dots, and panes require this rule to be followed
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| tmuxinator (this) | 13.7k | CLI | beginner | 27 days ago | Developers who restart the same project setup (editor, server, logs) every day |
| tmux-resurrect | 13.1k | Dev tool | beginner | 2.2 years ago | Terminal users who keep many tmux sessions open and dislike rebuilding them after a reboot |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.