🚀 Automate Your Terminal Workflow

Master sessions with Tmuxinator

Tmuxinator helps you manage complex terminal sessions easily. Create, manage, and automate your dev environment with simple YAML configuration files today.

200+

Places to Search

500K

Happy Users

100%

Free Forever!

Powerful Features

Everything You Need Manage Sessions

Tmuxinator gives you powerful tools to control your terminal. Create, save, and launch complex tmux sessions in seconds. Here’s what makes it special.

YAML Configuration

Define your tmux sessions with easy YAML files. No coding skills needed. Just write what you want.

Instant Session Start

Launch complex multi-window setups with one command. Save hours of manual work every single day.

Multiple Windows

Create as many windows as you need. Each window can have its own panes and commands ready to go.

Easy to Update

Change your setup anytime. Edit the YAML file and your session updates instantly. Simple as that.

Why Use Tmuxinator?

Experience the ultimate developer workflow. Designed to eliminate friction and maximize your focus.

Boost Productivity

Spend less time on setup and more time coding. Tmuxinator cuts your daily setup time to just seconds.

Reduce Stress

Never worry about losing your window layout again. Your perfect setup is always one command away.

Start Projects Fast

Jump into any project instantly. All your windows, panes, and commands are ready before you can blink.

Work Consistently

Same setup every time. No more forgetting to start that log watcher or open that config file.

Easy to Reproduce

Share your configs with your team. Everyone gets the same powerful setup in minutes.

Team Friendly

New team members can start working right away. Just share your YAML file and they're ready to go.

How to Download and Install

Getting Tmuxinator onto your machine is a simple process that takes less than a minute. Since it’s built with Ruby, you can install it using the standard Ruby package manager.

Step 1: Check Your Prerequisites

Before installing Tmuxinator, you need to ensure you have two things installed on your system: Tmux (obviously) and Ruby. Most macOS and Linux distributions come with Ruby pre-installed. You can check by running ruby -v in your terminal.

Step 2: Run the Install Command

Open your terminal and run the following command. This will download the latest version of Tmuxinator and set it up as a global command on your system:

gem install tmuxinator

*Note: If you encounter permission errors, you may need to use sudo gem install tmuxinator or use a Ruby version manager like RVM or rbenv.

Step 3: Configure Your Shell

For the best experience, we recommend setting up an alias. Adding alias mux="tmuxinator" to your .zshrc or .bashrc file allows you to start sessions with just three letters. It makes a big difference in speed!

Step 4: Verify the Installation

Once the installation is complete, verify everything is working by checking the version:
tmuxinator version
If you see a version number, you are all set! You can now start creating your first configuration file using tmuxinator new [project-name].
Pro Tip: Most developers prefer using their local package manager. On macOS, you can simply run brew install tmuxinator.

The Simple Workflow

Three simple steps to terminal bliss. No complex scripting required.

Create Config

Run `mux new project` to generate a fresh YAML configuration file.

Define Layout

Edit the YAML file to specify windows, panes, and startup commands.

Start Working

Type `mux start project` and watch your entire environment spring to life.

System Compatibility

Tmuxinator works wherever Tmux and Ruby can run.

Operating System	Status	Method
macOS	Full Support	Native or via Homebrew
Ubuntu / Debian	Full Support	Standard apt/gem install
Arch Linux	Full Support	Available in AUR
Windows (WSL)	Full Support	Highly recommended for Win
FreeBSD	Full Support	Via ports or packages
CentOS / Fedora	Full Support	Via dnf or ruby-gems

The Ultimate Tmuxinator Beginner's Guide

Everything you need to go from Zero to Terminal Pro in minutes.

Terminal multiplexing is one of the most powerful skills a developer can learn. Tmux itself is fantastic, but manually managing it can be tedious. That is where Tmuxinator comes in. In this guide, we will explore why you need it, how to configure it, and how to optimize your workflow for maximum output.

Why use Tmuxinator instead of standard Tmux?

Standard Tmux requires you to use shell commands to create sessions, windows, and panes. If you have a project that needs a server window, a database window, and three editor panes, you would have to type about 10-15 commands every time you start work.

Comparison: Manual vs Tmuxinator

Feature	Manual Tmux	Tmuxinator
Setup Time	2–5 minutes	1 second
Configuration	Complex Scripts	Readable YAML
Repeatability	Human Error Prone	100% Consistent
Sharing	Hard to transfer	Git-friendly

Your First Tmuxinator Config File

Config files are stored in ~/.config/tmuxinator/ by default. Here is a breakdown of what a standard developer config looks like:

name: my-app

# Project root directory
root: ~/projects/my-app

# Startup windows
windows:

– editor:
layout: main-vertical
panes:
– nvim

– server:
panes:
– npm run dev

– logs:
panes:
– tail -f log/development.log

Key Components Explained

Name: The unique identifier for your project. This is what you use with mux start [name].
Root: The directory where all commands will start. This ensures you don’t have to cd manually.
Windows: These represent the main tabs at the bottom of your Tmux session.
Panes: Sub-divisions within a window. You can run different processes in each one.
Layouts: Pre-set arrangements (tiled, horizontal, vertical) for your panes.

Expert Level: Advanced Hooks

One of the most underused features of Tmuxinator is the “Hooks” system. You can define actions that happen at various stages of the session lifecycle:

on_project_start: Runs before the tmux session is created. Use this to pull code or install dependencies.
on_project_exit: Runs when you kill the session. Perfect for cleaning up temp files or stopping background services.
on_project_stop: Runs right as the session is stopping.

Common Troubleshooting Tips

If your Tmuxinator isn’t behaving, check these three common issues first:

Indentation: YAML is very strict. Ensure your spaces are consistent (usually 2 spaces).
Window Names: Avoid using special characters in window names that Tmux might misinterpret.
Tmux Version: Ensure your Tmux version is 1.8 or higher. Tmuxinator relies on modern Tmux commands.

Conclusion: Tmuxinator is the bridge between having a “terminal setup” and having a “workflow”. By spending 5 minutes today to write a YAML config, you save dozens of hours over the next year. It is the best investment a terminal-focused developer can make.

What Developers Say

"Tmuxinator literally saved me 15 minutes of setup every single morning. I just type 'mux dev' and I'm coding."

Sarah K.

Senior Backend Engineer

"Configuring complex server environments for local testing used to be a nightmare. Now it's just one YAML file in our git repo."

Jason D.

DevOps Lead

"The best developer tool I've found this year. Clean, simple, and does exactly what it says on the tin."

Elena R.

Full Stack Developer

Frequently Asked Questions

Q: What is Tmuxinator?

A: It’s a terminal session manager that automates tmux workspace creation.

Q: Is it free to use?

A: Yes, it is open-source and free to use forever.

Q:Do I need Tmux to use it?

Yes, Tmux is a prerequisite for Tmuxinator.

Q:Why is YAML used for config?

YAML is used because it is human-readable, lightweight, and easy to edit compared to shell scripts.

Q: Does it work on Windows?

A: Yes, through WSL (Windows Subsystem for Linux).

Q: How do I install it?

A: Run ‘gem install tmuxinator’ in your terminal.

Q: I get a permissions error?

A: Try using a Ruby version manager or use sudo cautiously.

Q: What version of Ruby is needed?

A: Ruby 2.6 or higher is recommended.

Q: Can I install with Homebrew?

A: Yes, ‘brew install tmuxinator’ works on macOS.

Q: Does it need a database?

A: No, it is a standalone CLI tool.

How do I create a new project?

Run `tmuxinator new [project_name]` to open a new config in your editor.

How do I start a session?

Simply run `tmuxinator start [project_name]` or use the alias `mux start [name]`.

Q: Can I split panes vertically?

A: Yes, you define this in the window layout setting.

Q: How do I edit a config?

A: Run ‘mux edit [project_name]’.

Q: Can I use environment variables?

A: Yes, it supports ERB for dynamic values.

Q: The command ‘mux’ is not found.

A: Ensure you’ve added the alias to your shell profile.

Q: Panes aren’t splitting correctly.

A: Check your ‘layout’ setting in the YAML file.

Q: Commands fail on startup.

A: Verify the ‘root’ directory is correct.

Q: Tmux is version 1.6, help!

A: Please upgrade tmux to at least 1.8 for compatibility.

Q: Color issues in terminal.

A: Set ‘force_utf8: true’ in your config.