bastos 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.ymlin 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-verticalmain_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(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.