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

Command	Alias	Purpose
`tmuxinator new PROJECT`	`n`	Create/edit project config
`tmuxinator new --local PROJECT`	-	Create `.tmuxinator.yml` in current dir
`tmuxinator start PROJECT`	`s`	Launch session
`tmuxinator start PROJECT -n NAME`	-	Launch with custom session name
`tmuxinator start PROJECT --append`	-	Append windows to current session
`tmuxinator stop PROJECT`	-	Kill session
`tmuxinator stop-all`	-	Kill all tmuxinator sessions
`tmuxinator list`	`l`, `ls`	List all projects
`tmuxinator copy OLD NEW`	`c`, `cp`	Duplicate config
`tmuxinator delete PROJECT`	`rm`	Remove config
`tmuxinator debug PROJECT`	-	Show generated shell commands
`tmuxinator doctor`	-	Diagnose issues

Configuration Locations

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

Complete Configuration Reference

Project Options

Option	Type	Default	Description
`name`	string	required	Session name (no periods allowed)
`root`	string	`~/`	Base directory for all windows
`socket_name`	string	-	Custom tmux socket name
`attach`	boolean	`true`	Auto-attach to session after creation
`startup_window`	string/int	first	Window to select on startup (name or index)
`startup_pane`	int	`0`	Pane to select within startup window
`tmux_options`	string	-	Options passed to tmux (e.g., `-f ~/.tmux.alt.conf`)
`tmux_command`	string	`tmux`	Alternative command (e.g., `byobu`)
`pre_window`	string/list	-	Commands run before each pane's commands
`enable_pane_titles`	boolean	`false`	Show pane titles (tmux 2.6+)
`pane_title_position`	string	-	Title position: `top`, `bottom`, or `off`
`pane_title_format`	string	-	Custom pane title format string

Lifecycle Hooks

Hook	When It Runs
`on_project_start`	Every session start, before windows created
`on_project_first_start`	Only on initial session creation
`on_project_restart`	When reattaching to existing session
`on_project_exit`	When detaching from session
`on_project_stop`	When `tmuxinator stop` is called
`pre_window`	Before each pane's commands (use for env setup)

All hooks accept a string or list of strings:

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

Window Options

Option	Type	Default	Description
`layout`	string	-	Pane layout (see Layout Options)
`root`	string	project root	Override working directory for this window
`panes`	list	-	List of pane definitions
`synchronize`	string	-	Sync pane input: `before` or `after`

Pane Options

Option	Type	Description
`pane_title`	string	Title for this pane (requires `enable_pane_titles`)
`commands`	list	Commands to run (alternative to inline list)

Layout Options

Layout	Description
`even-horizontal`	Panes spread left-to-right, equal width
`even-vertical`	Panes spread top-to-bottom, equal height
`main-horizontal`	Large pane on top, others spread below
`main-vertical`	Large pane on left, others spread right
`tiled`	Even grid of panes

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

Problem	Solution
Window names reset	Add `export DISABLE_AUTO_TITLE=true` to shell rc
Commands truncated	Move long commands to scripts, source them
Project name invalid	Remove periods from name (tmux uses `.` as delimiter)
Layout inconsistent	Use `tmuxinator debug PROJECT` to see generated script
Session exists error	Use `tmuxinator stop PROJECT` first, or `-n` for new name
Panes not in order	Layouts applied after creation; order may shift
rbenv/nvm not loading	Use `pre_window` to set version before commands
Hooks not running	Check hook names (deprecated `pre`/`post` → `on_project_*`)

Debugging

# Show what tmuxinator will execute
tmuxinator debug myproject

# Check for configuration issues
tmuxinator doctor

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

# Test ERB processing
ruby -rerb -ryaml -e "puts ERB.new(File.read('~/.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.

tmuxinator

Safety Notice

Copy this and send it to your AI assistant to learn