Tmuxinator Deployment and Usage Guide

1. Prerequisites

Before installing tmuxinator, ensure you have the following:

Ruby: Currently maintained Ruby versions (3.x recommended). Avoid using system Ruby; use RVM or rbenv instead.
tmux: Version 1.8 or later (⚠️ Version 2.5 is explicitly not supported due to issue #536)
Editor: $EDITOR environment variable configured (e.g., vim, nano, code)
Shell: Bash, Zsh, or Fish for completion support

Verify prerequisites:

ruby --version          # Should be 3.0+
tmux -V                 # Should be 1.8+, not 2.5
echo $EDITOR            # Should not be empty

2. Installation

Method 1: RubyGems (Recommended)

gem install tmuxinator

Method 2: Homebrew

brew install tmuxinator

Note: Some users have reported issues with Homebrew installation. Use RubyGems if you encounter problems.

Shell Completion Setup

Bash:

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.bash -O /etc/bash_completion.d/tmuxinator.bash

Zsh:

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.zsh -O /usr/local/share/zsh/site-functions/_tmuxinator

Fish:

wget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.fish -O ~/.config/fish/completions/tmuxinator.fish

Verification

tmuxinator doctor    # Check for configuration problems
tmuxinator version   # Verify installation

3. Configuration

Configuration Directory

Tmuxinator searches for projects in the following order:

$TMUXINATOR_CONFIG (if set)
$XDG_CONFIG_HOME/tmuxinator (default: ~/.config/tmuxinator)
~/.tmuxinator (legacy)

Create the directory:

mkdir -p ~/.config/tmuxinator

Environment Variables

# Set custom config directory
export TMUXINATOR_CONFIG="$HOME/.tmuxinator"

# Set default editor for project files
export EDITOR="vim"
# or
export EDITOR="code --wait"

Project File Structure

Create a project configuration (~/.config/tmuxinator/myapp.yml):

name: myapp
root: ~/projects/myapp

# Optional: Custom tmux socket
# socket_name: foo

# Hooks
on_project_start: echo "Starting project"
on_project_exit: echo "Exiting project"

# Runs before each window/pane
pre_window: rbenv shell 3.0.0

# Tmux options
tmux_options: -f ~/.tmux.conf

# Startup behavior
startup_window: editor
startup_pane: 1
attach: true

# Windows configuration
windows:
  - editor:
      layout: main-vertical
      panes:
        - vim
        - guard
  - server:
      root: ~/projects/myapp/server
      panes:
        - bundle exec rails server
        - tail -f log/development.log
  - logs:
      layout: tiled
      panes:
        - tail -f /var/log/syslog
        - htop

Important: Project names cannot contain dots (.) as tmux uses them internally to delimit windows and panes.

4. Build & Run

Basic Usage Workflow

Create a new project:

tmuxinator new myproject    # Creates ~/.config/tmuxinator/myproject.yml
# or
tmuxinator n myproject      # Short alias

Edit an existing project:

tmuxinator open myproject   # Opens in $EDITOR
# or
tmuxinator edit myproject

Start a session:

tmuxinator start myproject
# or
tmuxinator start myproject alias_name    # Reuse config with different session name

Stop a session:

tmuxinator stop myproject
tmuxinator stop_all                      # Stop all tmuxinator sessions

List projects:

tmuxinator list

Local Project Mode For project-specific configs stored in version control:

# Creates ./.tmuxinator.yml in current directory
tmuxinator new --local myproject

# Start local project
tmuxinator local
# or
tmuxinator start -p ./.tmuxinator.yml

Development Setup (Contributing)

git clone https://github.com/tmuxinator/tmuxinator.git
cd tmuxinator
bundle install
bundle exec rake spec    # Run tests
bundle exec tmuxinator   # Run local version

Debug Mode

View generated tmux commands without executing:

tmuxinator debug myproject

5. Deployment

Since tmuxinator is a local development tool, "deployment" refers to distributing configurations across team environments:

Team Configuration Distribution

Commit local configs to repository:

tmuxinator new --local dev-env
git add .tmuxinator.yml
git commit -m "Add tmuxinator config"

Standardized team setup:

# On new developer machines
gem install tmuxinator
git clone <repo>
cd <repo>
tmuxinator local    # Uses ./.tmuxinator.yml

Shared configuration repository:

# Company-wide configs
git clone https://internal-git/tmuxinator-configs ~/.config/tmuxinator

CI/CD Integration

For automated testing of tmuxinator configs:

# Validate YAML syntax
tmuxinator debug myproject > /dev/null

# Check if project loads
tmuxinator start myproject --detach
tmuxinator stop myproject

6. Troubleshooting

Ruby Version Issues

Problem: gem install fails or warns about Ruby version Solution: Install via rbenv/RVM instead of system Ruby:

rbenv install 3.2.0
rbenv global 3.2.0
gem install tmuxinator

tmux 2.5 Compatibility

Problem: Sessions fail to start or attach properly Solution: Upgrade tmux to 1.8+, 2.6+, or latest (avoid exactly 2.5):

# Check version
tmux -V

# Upgrade (Ubuntu/Debian)
sudo apt-get install tmux

# Upgrade (macOS)
brew upgrade tmux

Homebrew Installation Issues

Problem: Command not found or Ruby path errors after brew install Solution: Use RubyGems installation instead:

brew uninstall tmuxinator
gem install tmuxinator

Project Not Found

Problem: Project could not be found error Solution: Check config directory resolution:

tmuxinator doctor                    # Shows active config path
ls ~/.config/tmuxinator/*.yml       # Verify file exists
export TMUXINATOR_CONFIG=~/.config/tmuxinator    # Force path if needed

Completion Not Loading

Problem: Tab completion doesn't work Solution: Ensure completion files are in $fpath (Zsh) or /etc/bash_completion.d/ (Bash):

# Zsh - add to ~/.zshrc if needed
fpath=(/usr/local/share/zsh/site-functions $fpath)

# Reload shell
exec $SHELL -l

Pane Synchronization Deprecation Warning

Problem: Warnings about synchronize option behavior Solution: Update project YAML to use explicit timing:

windows:
  - sync-window:
      synchronize: after    # or 'before' for legacy behavior
      panes:
        - command1
        - command2

How to Deploy & Use tmuxinator/tmuxinator