Tmuxinator

Overview

Tmuxinator manages complex tmux sessions through YAML configuration files. Define windows, panes, layouts, and startup commands once, then launch reproducible development environments with a single command.

When to Use

• Setting up multi-window/pane development environments
• Automating project-specific terminal layouts
• Creating reproducible tmux sessions across machines
• Debugging tmuxinator configuration issues

Not for: Simple single-window sessions (just use tmux directly)

Quick Reference

Configuration Locations

1. ~/.tmuxinator/PROJECT.yml (default)
2. $XDG_CONFIG_HOME/tmuxinator/PROJECT.yml
3. $TMUXINATOR_CONFIG/PROJECT.yml
4. .tmuxinator.yml in project root (local config)

Complete Configuration Reference

Project Options

Lifecycle Hooks

All hooks accept a string or list of strings:

on_project_start:
  - docker-compose up -d
  - redis-server --daemonize yes

Window Options

Pane Options

Layout Options

Control main pane size:

• main_pane_width: columns or percentage for main-vertical
• main_pane_height: rows or percentage for main-horizontal

Custom layouts use tmux's layout string format (copy from tmux list-windows).

Full Example Configuration

# Required
name: myproject

# Project root (default: ~/)
root: ~/Code/myproject

# Optional: custom tmux socket
socket_name: myproject

# Optional: pass options to tmux command
tmux_options: -f ~/.tmux.custom.conf

# Optional: use alternative tmux (e.g., byobu)
tmux_command: tmux

# Optional: auto-attach to session (default: true)
attach: true

# Optional: select specific window/pane on startup
startup_window: editor
startup_pane: 1

# Optional: pane titles (tmux 2.6+)
enable_pane_titles: true
pane_title_position: top
pane_title_format: " #T "

# Lifecycle hooks
on_project_start: docker-compose up -d
on_project_first_start: npm install
on_project_restart: echo "Welcome back"
on_project_exit: docker-compose stop
on_project_stop: docker-compose down

# Run before every pane command (env managers, etc.)
pre_window: nvm use 18

# Windows
windows:
  # Simple: window name with single command
  - server: bundle exec rails s

  # Window with layout and multiple panes
  - editor:
      layout: main-vertical
      # Synchronize pane input ('before' or 'after' pane creation)
      synchronize: after
      panes:
        - vim .
        - guard
        - # empty pane (just shell)

  # Window with custom root
  - frontend:
      root: ~/Code/myproject/client
      panes:
        - npm start
        - npm run test -- --watch

  # Pane with multiple sequential commands
  - backend:
      panes:
        -
          - cd api
          - source venv/bin/activate
          - python manage.py runserver

  # Named panes with titles
  - monitoring:
      panes:
        - pane_title: "Logs"
          commands:
            - tail -f logs/app.log
        - pane_title: "System"
          commands:
            - htop

Dynamic Configuration (ERB)

Configs are processed as ERB templates before YAML parsing:

# Environment variables
root: <%= ENV["PROJECT_DIR"] || "~/Code/default" %>
name: <%= ENV["USER"] %>-dev

# Command-line arguments: tmuxinator start myproject arg1 arg2
# Access via @args array (positional)
root: <%= @args[0] %>

# Key-value arguments: tmuxinator start myproject env=prod db=mysql
# Access via @settings hash
<% if @settings["env"] == "production" %>
root: /var/www/app
<% else %>
root: ~/Code/app
<% end %>

# Conditional windows
windows:
  - main: vim
<% if @settings["with_docker"] %>
  - docker: docker-compose logs -f
<% end %>

Window and Pane Patterns

Simple window with command:

windows:
  - server: npm run dev

Window with multiple panes:

windows:
  - dev:
      panes:
        - vim
        - npm run watch
        - npm run test -- --watch

Pane with sequential commands (send-keys style):

windows:
  - build:
      panes:
        - # Commands sent sequentially
          - cd backend
          - source venv/bin/activate
          - python manage.py runserver

Per-window root override:

windows:
  - frontend:
      root: ~/Code/myproject/frontend
      panes:
        - npm start

Synchronized panes (same input to all):

windows:
  - cluster:
      synchronize: after
      panes:
        - ssh server1
        - ssh server2
        - ssh server3

Named panes with titles (tmux 2.6+):

enable_pane_titles: true
pane_title_position: top

windows:
  - main:
      panes:
        - pane_title: "Editor"
          commands:
            - vim
        - pane_title: "Tests"
          commands:
            - npm test

Common Patterns

Full-Stack Development

name: fullstack
root: ~/Code/myapp

on_project_start:
  - docker-compose up -d postgres redis

on_project_stop:
  - docker-compose down

pre_window: nvm use 18

windows:
  - editor:
      layout: main-vertical
      panes:
        - vim .
        - lazygit
  - backend:
      root: ~/Code/myapp/api
      panes:
        - npm run dev
        - npm run test -- --watch
  - frontend:
      root: ~/Code/myapp/web
      panes:
        - npm start
        - # empty for commands
  - services:
      panes:
        - docker-compose logs -f
        - htop

Remote Development (SSH)

name: remote-dev
root: ~

windows:
  - remote:
      panes:
        - # Use array for SSH commands
          - ssh user@server
          - cd /var/www/app
          - vim .

Microservices

name: microservices
root: ~/Code

windows:
  - api-gateway:
      root: ~/Code/gateway
      panes:
        - npm run dev
  - users-service:
      root: ~/Code/users
      panes:
        - npm run dev
  - orders-service:
      root: ~/Code/orders
      panes:
        - npm run dev
  - logs:
      layout: tiled
      panes:
        - docker logs -f gateway
        - docker logs -f users
        - docker logs -f orders

Environment-Aware Config

name: app-<%= @settings["env"] || "dev" %>
root: <%= @settings["env"] == "prod" ? "/var/www/app" : "~/Code/app" %>

<% if @settings["env"] == "prod" %>
attach: false
on_project_start: sudo systemctl start nginx
<% end %>

windows:
  - app:
      panes:
        - <%= @settings["env"] == "prod" ? "tail -f /var/log/app.log" : "npm run dev" %>

Troubleshooting

Debugging

# Show what tmuxinator will execute
tmuxinator debug myproject

# Check for configuration issues
tmuxinator doctor

# Verify YAML syntax
ruby -ryaml -e "YAML.load_file(File.expand_path('~/.tmuxinator/myproject.yml'))"

# Test ERB processing
ruby -rerb -ryaml -e "puts ERB.new(File.read(File.expand_path('~/.tmuxinator/myproject.yml'))).result"

Installation

# Preferred (requires Ruby)
gem install tmuxinator

# Alternative
brew install tmuxinator

Requires tmux 1.8+ (avoid 2.5 due to bugs). Shell completions available in the GitHub repo's completion/ directory.