Tmuxinator Integration

The dotfiles now include seamless integration with tmuxinator for complex project configurations, while maintaining backward compatibility with simple .tmux templates.

Installation

# Arch/CachyOS
sudo pacman -S tmuxinator

# Or via Ruby gems
gem install tmuxinator

Quick Start

# Create a new tmuxinator project
txi-new myproject dev

# Edit the configuration
txi-edit myproject

# Start the project
txi myproject

# Or use the unified tw command (auto-detects tmuxinator)
tw myproject

Command Reference

Tmuxinator Commands (txi-*)

Command	Alias	Description
`txi <name>`	-	Start/attach to tmuxinator project
`txi-new <name> [template]`	`txin`	Create new project
`txi-edit <name>`	`txie`	Edit project YAML file
`txi-list`	`txil`	List all tmuxinator projects
`txi-delete <name>`	`txid`	Delete project
`txi-stop <name>`	`txis`	Stop running session
`txi-templates`	`txit`	Show available templates
`txi-import <template> [name]`	-	Convert .tmux to tmuxinator
`txif`	-	Fuzzy search and start
`txi-help`	`txih`	Show help

Available Templates

Template	Description
`dev`	Development: editor + terminal + server + logs
`ops`	Operations: monitoring grid + services + SSH
`web`	Web development: editor + server + frontend + db
`data`	Data science: jupyter + code + data + terminal
`minimal`	Single window, single pane

Integration with tw-* Commands

The existing tw commands automatically detect tmuxinator:

# If "myproject.yml" exists in ~/.config/tmuxinator/, uses tmuxinator
# Otherwise, uses simple .tmux template
tw myproject

Priority order:

Running tmux session with matching name
Tmuxinator project (if exists)
Simple .tmux template

Example Tmuxinator Project

# ~/.config/tmuxinator/webapp.yml
name: webapp
root: ~/projects/webapp

# Activate virtualenv before all windows
pre_window: source venv/bin/activate

windows:
  - editor:
      layout: main-vertical
      panes:
        - vim .
        - # terminal
        
  - server:
      panes:
        - python manage.py runserver
        
  - frontend:
      layout: even-horizontal
      panes:
        - npm run watch
        - npm run tailwind
        
  - database:
      panes:
        - pgcli mydb

Configuration

Add to dotfiles.conf:

# ============================================================================
# Tmuxinator Settings
# ============================================================================

TMUXINATOR_ENABLED="auto"             # auto, true, false
TMUXINATOR_CONFIG_DIR="$HOME/.config/tmuxinator"
TW_PREFER_TMUXINATOR="true"           # Prefer tmuxinator over simple templates

Simple Templates vs Tmuxinator

Feature	Simple (.tmux)	Tmuxinator (.yml)
Learning curve	Minimal	Moderate
Per-pane commands	No	Yes
Environment variables	No	Yes
Pre/post hooks	No	Yes
Window names	No	Yes
Complex layouts	Limited	Full support
Startup speed	Fast	Slightly slower

Use simple templates for:

Quick, ad-hoc layouts
Simple split configurations
Layouts you'll customize each time

Use tmuxinator for:

Persistent project configurations
Projects with specific startup commands
Complex multi-window setups
Team-shared configurations

Import Existing Templates

Convert your simple .tmux templates to tmuxinator format:

# Import the 'dev' template as a tmuxinator project
txi-import dev myproject

# Then customize it
txi-edit myproject

Tips

Project Discovery: The tw and twf commands show both active sessions and available tmuxinator projects
Git Integration: When starting a workspace in a git repo, the first pane automatically cds to the repo root
Synchronized Input: Toggle with tw-sync to type in all panes simultaneously
Fuzzy Finding: Use twf or txif for quick project selection with fzf

4.1 KiB Raw Blame History