tmuxinator — Manage Complex tmux Sessions with YAML Configs

Introduction

tmuxinator automates the creation of tmux sessions using YAML configuration files. Instead of manually splitting panes, opening windows, and running startup commands every time you sit down to work, you define your layout once and launch the entire environment with a single command.

What tmuxinator Does

• Creates tmux sessions with multiple named windows and split panes from a YAML config
• Runs startup commands in each pane automatically (servers, watchers, REPLs, logs)
• Supports project-level configs so each codebase has its own tmux layout
• Provides commands to list, edit, copy, and delete saved project configurations
• Integrates with shell completion for fast project switching

Architecture Overview

tmuxinator is a Ruby CLI that reads a YAML file describing a session layout, then translates it into a sequence of tmux commands. Each window definition maps to tmux new-window, pane splits map to split-window with layout directives, and commands are sent via send-keys. The session is created in detached mode first, then attached, ensuring all panes are initialized before the user sees them.

Self-Hosting & Configuration

• Requires Ruby 2.6+ and tmux 1.8+ installed on the system
• Project configs are stored in ~/.config/tmuxinator/ as YAML files
• Use tmuxinator new <name> to generate a config template with annotated examples
• Set a root path in the config to auto-cd all panes into the project directory
• Define pre_window commands that run in every pane before the pane-specific command

Key Features

• Declarative YAML syntax for defining complex multi-window, multi-pane layouts
• Per-pane startup commands for launching servers, databases, log tails, and editors simultaneously
• ERB templating support in YAML files for dynamic configuration based on environment variables
• Tab completion for Bash, Zsh, and Fish shells
• Local project configs via .tmuxinator.yml in a repo root for team-shared layouts

Comparison with Similar Tools

• tmuxp — Python-based tmux session manager with JSON/YAML support; tmuxinator is Ruby-based with a wider plugin ecosystem
• teamocil — similar YAML-based tmux automation but less actively maintained
• Zellij — a modern terminal workspace that replaces tmux entirely; tmuxinator extends tmux rather than replacing it
• devbox / direnv — manage environment variables and dependencies; tmuxinator manages terminal layout and startup commands

FAQ

Q: Do I need Ruby installed? A: Yes, tmuxinator is a Ruby gem. Install it with gem install tmuxinator or through your system package manager.

Q: Can I use tmuxinator without a global installation? A: You can use Bundler to install it locally per project, or run it via npx-style Ruby tools like bundler exec.

Q: How do I define pane splits? A: Under a window definition, add a panes key with a list of commands. tmuxinator splits them using tmux's even-horizontal layout by default, or you can specify a custom layout string.

Q: Can different team members share a tmuxinator config? A: Yes, commit a .tmuxinator.yml file to the project root. Team members can start it with tmuxinator local or by specifying the file path.

Sources

• https://github.com/tmuxinator/tmuxinator
• https://github.com/tmuxinator/tmuxinator#readme