tmux

name	tmux
description	tmux and tmuxp session configuration, management, and troubleshooting. Use when creating, editing, debugging, or optimizing tmuxp YAML configs, designing tmux workspace layouts, fixing tmux session errors, managing multi-environment terminal setups, or working with tmux panes, windows, and sessions. Also use when the user mentions tmuxp, .tmuxp, tmux layouts, session_name, or terminal workspace organization.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob

tmux & tmuxp Skill

Create, edit, debug, and optimize tmux sessions via tmuxp YAML configurations.

Quick Decisions

Task	Approach
New project workspace	Create tmuxp YAML from template
Fix session load error	Check session_name, YAML syntax, tool availability
Multi-environment K8s	Use environment vars + per-env windows with safety guards
Simple dev setup	2-3 windows: editor, server, terminal
Complex infra	before_script validation + helper scripts + monitoring windows
Capture existing layout	tmuxp freeze then clean up the output

Session Name Rules

tmux session names cannot contain periods (.) or colons (:).

Common pitfall: using ${USER} in session_name when the username contains periods (e.g., first.last). Always use a static name or sanitize:

# BAD - breaks if USER contains periods
session_name: ${USER}-project

# GOOD - static name
session_name: project-dev

# GOOD - sanitized
session_name: project-${USER//\./-}

Configuration Structure

session_name: project-name          # Required. No periods or colons.
start_directory: ~/Projects/foo     # Default working dir for all windows
environment:                        # Session-wide env vars
  PROJECT_ROOT: ~/Projects/foo
suppress_history: false             # Whether to hide commands from shell history

before_script: |                    # Runs before session creation. Exit 1 = abort.
  echo "Validating..."

after_script: |                     # Runs after session is destroyed
  echo "Cleaning up..."

windows:
  - window_name: editor             # Window identifier
    focus: true                     # Make this the active window on load
    layout: main-vertical           # Pane layout
    start_directory: ~/Projects/foo/src
    options:
      main-pane-width: 70%          # Layout-specific options
    shell_command_before:            # Runs in ALL panes before pane commands
      - source ~/.zshrc
    panes:
      -                   
        
            
       
              

Layouts

Layout	Use For	Pane Arrangement
main-vertical	Editor + sidebars	Large left, stacked right
main-horizontal	Logs + status	Large top, split bottom
even-horizontal	Equal side-by-side	Equal horizontal splits
even-vertical	Equal stacked	Equal vertical splits
tiled	Monitoring dashboards	Grid of equal panes

Control main pane size via options:

options:
  main-pane-width: 70%    # For main-vertical
  main-pane-height: 65%   # For main-horizontal

Capture a custom layout from a running session:

tmux display-message -p '#{window_layout}'
# Returns: "bb62,159x48,0,0{79x48,0,0,79x48,80,0}"

Pane Definitions

panes:
  # Simple command
  - vim README.md

  # Multiple commands
  - shell_command:
      - cd ~/project
      - source .venv/bin/activate
      - python app.py

  # Empty pane
  - null     # or: blank, pane

  # With focus
  - focus: true
    shell_command:
      - k9s

Environment Variables

environment:
  # Static values
  PROJECT_NAME: my-app

  # Reference existing vars (expanded at load time)
  HOME_DIR: ${HOME}

  # Multi-environment pattern
  K8S_CTX_DEV: aks-myapp-dev
  K8S_CTX_STG: aks-myapp-stg
  K8S_CTX_PRD: aks-myapp-prd

  # Defaults
  EDITOR: ${EDITOR:-vim}

Never hardcode secrets. Reference env vars from the shell: ${AZURE_SUBSCRIPTION_ID}.

before_script Validation

Use before_script to validate prerequisites. Exit 1 aborts session creation:

before_script: |
  # Check project exists
  [ -d "$PROJECT_ROOT" ] || { echo "Project not found"; exit 1; }

  # Check required tools
  for tool in kubectl terraform docker; do
    command -v $tool >/dev/null || echo "Warning: $tool not found"
  done

  # Check connectivity
  kubectl cluster-info >/dev/null 2>&1 || echo "Warning: Cannot reach cluster"

Production Safety Patterns

Protect production environments with read-only access and warnings:

- window_name: k8s-prod
  panes:
    - shell_command:
        - echo "PRODUCTION - READ-ONLY ACCESS"
        - echo "DO NOT use: apply, delete, edit, patch"
        - kubectl config use-context $K8S_CTX_PRD
        - k9s --readonly

CLI Commands

tmuxp load config-name          # Load from ~/.tmuxp/
tmuxp load ./path/to/file.yaml  # Load from path
tmuxp load -y config-name       # Skip confirmation prompt
tmuxp load -d config-name       # Load detached (background)
tmuxp ls                        # List available configs
tmuxp freeze session-name       # Capture running session to YAML
tmuxp convert file.json         # Convert JSON config to YAML
tmuxp edit config-name          # Edit config in $EDITOR
tmuxp debug-info                # Show environment info

Troubleshooting

Error	Cause	Fix
BadSessionName: contains periods	session_name has . (often from ${USER})	Remove ${USER} prefix or sanitize
BadSessionName: contains colons	session_name has :	Remove colons from name
Session already exists	Duplicate session_name	Kill old: tmux kill-session -t name
Commands not executing	Shell compatibility	Test commands manually first
Layout broken	Terminal too small for layout	Use predefined layouts or test with tmuxp load -d
Env vars not expanding	Wrong syntax	Use ${VAR} not $VAR in YAML values

Debug: tmuxp -v load config.yaml for verbose output.

References

• WORKFLOWS.md - Common workflow patterns (dev, infra, monitoring)
• BEST-PRACTICES.md - Production patterns, safety, organization
• templates/ - Ready-to-use config templates

Workflow: Create New Config

1. Identify the project type (dev, infra, monitoring, mixed)
2. Choose a template from templates/
3. Set session_name (no periods/colons), start_directory, environment vars
4. Design windows by function (editor, server, logs, k8s, etc.)
5. Pick layouts matching each window's purpose
6. Add before_script validation if the project has external dependencies
7. Add production safety guards for any prod-access windows
8. Test: tmuxp load -d config.yaml then tmux attach -t session-name

---

Gotchas

• Session names with periods break the unix-socket path: ${USER} containing . (e.g. first.last) produces BadSessionName because tmux uses the name in /tmp/tmux-UID/ socket path. Use a static name or ${USER//\./-} sanitization.
• before_script runs in a fresh shell, not your interactive zsh: Aliases, functions, and .zshrc-sourced env vars are absent. command -v works but myalias does not. Source ~/.zshrc explicitly if you depend on it.
• shell_command_before runs in EVERY pane of the window: Heavy commands (sourcing 500ms+ of zsh config, activating venvs) multiply latency — a 4-pane window adds ~2s to session load. Use per-pane shell_command instead when only one pane needs it.
• tmuxp freeze captures live state, not intent: Output includes the random working directories, history-expanded commands, and the literal pane sizes — review and clean before committing. Frozen YAML is a starting point, not a finished config.
• Env var expansion happens at YAML load, not pane start: environment: FOO: ${BAR} resolves $BAR from the shell that invoked tmuxp load. If $BAR is unset there, it stays empty even if a later pane defines it.
• focus: true on multiple panes silently picks the last one: No error, no warning — the file just looks misconfigured at runtime. Validate with grep -c "focus: true" per window before debugging.