# tmuxinator — Manage Complex tmux Sessions with YAML Configs

> A Ruby gem that lets you define tmux sessions, windows, and panes in YAML files and launch them with a single command. Eliminates repetitive manual setup of development environments.

## Install

Save as a script file and run:

# tmuxinator — Manage Complex tmux Sessions with YAML Configs

## Quick Use
```bash
gem install tmuxinator
tmuxinator new my-project
# Edit the generated YAML, then:
tmuxinator start my-project
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-180b615a
Author: Script Depot