Tmux

tmux & tmuxp Skill

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

Quick Decisions

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:
      - focus: true                 # Active pane within window
        shell_command:
          - vim .
      - shell_command:
          - npm test -- --watch

Layouts

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

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.

tmuxp Best Practices

Table of Contents

1. Naming Conventions 2. Window Organization 3. Production Safety 4. Helper Scripts 5. Error Handling 6. Performance 7. File Organization 8. Common Pitfalls

---

Naming Conventions

Session Names

• Use kebab-case: project-name, k8s-ops, dev-workspace
• No periods (tmux rejects them): juliano-dev not juliano.dev
• No colons (tmux rejects them): k8s-dev not k8s:dev
• Keep names short and descriptive for tmux switch-client -t name
• Avoid ${USER} prefix — usernames often contain periods

Window Names

Use descriptive names. Emojis are optional but help visual scanning:

# Without emojis (clean, functional)
- window_name: editor
- window_name: k8s-dev
- window_name: monitoring

# With emojis (visual scanning in tmux status bar)
- window_name: "editor"
- window_name: "k8s-dev"
- window_name: "monitoring"

File Names

• Match the session purpose: project-dev.yaml, k8s-monitoring.yaml
• Include environment when relevant: myapp-stg.yaml
• Use kebab-case consistently

---

Window Organization

Group by Function

Organize windows by role, not by tool:

# GOOD - grouped by function
windows:
  - window_name: develop     # Editor, tests, git
  - window_name: serve       # Dev server, hot reload
  - window_name: infra       # Terraform, cloud CLI
  - window_name: deploy      # K8s, Helm, ArgoCD
  - window_name: observe     # Logs, metrics, events

# BAD - grouped by tool
windows:
  - window_name: vim
  - window_name: kubectl
  - window_name: terraform

Window Count Guidelines

Focus Management

Always set focus: true on the window and pane you want active on load:

windows:
  - window_name: editor
    focus: true              # This window is active on session start
    panes:
      - focus: true          # This pane is active within the window
        shell_command:
          - vim .
      - shell_command:
          - npm test

---

Production Safety

Tiered Access Pattern

Implement increasing restrictions as environments get more critical:

DEV:     Full access, all commands
STAGING: Warnings displayed, careful messaging
PROD:    Read-only tools, explicit warnings, no write commands

Read-Only Production

- window_name: k8s-prod
  panes:
    - shell_command:
        - echo "PRODUCTION - READ-ONLY"
        - echo "Allowed: get, describe, logs, top"
        - echo "Forbidden: apply, delete, edit, patch, scale"
        - k9s --context $K8S_CTX_PRD --readonly

Confirmation Helpers

Generate safety wrappers in before_script:

before_script: |
  HELPER="$HOME/.tmuxp-helpers-${PROJECT_NAME}.sh"
  cat > "$HELPER" << 'SCRIPT'
  kprd() {
    echo "WARNING: Switching to PRODUCTION"
    read -p "Are you sure? (y/N) " -n 1 -r
    echo
    [[ $REPLY =~ ^[Yy]$ ]] || return 1
    kubectl config use-context "$K8S_CTX_PRD"
  }
  SCRIPT

---

Helper Scripts

Auto-Generated Helpers

Create project-specific helper scripts via before_script:

before_script: |
  HELPER="${HOME}/.tmuxp-helpers-${PROJECT_NAME}.sh"
  if [ ! -f "$HELPER" ]; then
    cat > "$HELPER" << 'EOF'
    # Quick context switching
    kdev() { kubectl config use-context "$K8S_CTX_DEV"; }
    kstg() { kubectl config use-context "$K8S_CTX_STG"; }

    # Common operations
    pods() { kubectl get pods -n "$APP_NS" "$@"; }
    logs() { kubectl logs -n "$APP_NS" -f "$@"; }
    events() { kubectl get events -n "$APP_NS" --sort-by='.lastTimestamp'; }

    # Help
    project-help() {
      echo "Available commands:"
      echo "  kdev/kstg  - Switch K8s context"
      echo "  pods       - List pods"
      echo "  logs       - Tail logs"
      echo "  events     - Show events"
    }
    EOF
    echo "Helper script created: $HELPER"
  fi

shell_command_before for Auto-Loading

windows:
  - window_name: k8s
    shell_command_before:
      - source "$HOME/.tmuxp-helpers-${PROJECT_NAME}.sh" 2>/dev/null
    panes:
      - kubectl get pods

---

Error Handling

Graceful Failures in Panes

Always handle missing tools or connectivity issues:

panes:
  # GOOD - handles failure gracefully
  - shell_command:
      - kubectl get pods 2>/dev/null || echo "Cannot connect to cluster"
      - command -v stern >/dev/null && stern ".*" || kubectl logs -f --tail=50

  # BAD - crashes or shows raw errors
  - shell_command:
      - kubectl get pods
      - stern ".*"

before_script Validation Levels

before_script: |
  # CRITICAL - abort if missing
  [ -d "$PROJECT_ROOT" ] || { echo "Error: project not found"; exit 1; }

  # IMPORTANT - warn but continue
  command -v kubectl >/dev/null || echo "Warning: kubectl not found"

  # NICE TO HAVE - silent fallback
  command -v stern >/dev/null 2>&1  # Used later with fallback

Common Validation Checks

# Directory exists
[ -d "$PROJECT_ROOT" ] || exit 1

# Tool available
command -v kubectl >/dev/null || echo "Warning: kubectl missing"

# Cloud authenticated
az account show >/dev/null 2>&1 || echo "Warning: Not logged into Azure"

# K8s cluster reachable
kubectl cluster-info >/dev/null 2>&1 || echo "Warning: Cluster unreachable"

# Docker running
docker info >/dev/null 2>&1 || echo "Warning: Docker not running"

# Git repo valid
[ -d .git ] || echo "Warning: Not a git repository"

---

Performance

Avoid Slow Commands in Panes

Commands in panes run sequentially. Slow commands block the pane:

# BAD - blocks pane for seconds
panes:
  - shell_command:
      - az resource list -g mygroup -o table   # 5+ seconds
      - kubectl get pods                        # Waits for above

# GOOD - fast startup, run slow commands on demand
panes:
  - shell_command:
      - echo "Run: az resource list -g mygroup -o table"
      - echo "Run: kubectl get pods"

Use watch for Polling (Not Loops)

# GOOD - built-in, clean exit with Ctrl+C
- watch -n 5 "kubectl get pods"

# OK for complex logic - but harder to interrupt
- while true; do kubectl get pods; sleep 5; done

Detached Loading for Testing

# Test config without attaching
tmuxp load -d config.yaml

# Then attach if it worked
tmux attach -t session-name

---

File Organization

For Small Collections (< 20 configs)

Flat structure in ~/.tmuxp/:

~/.tmuxp/
├── project-a.yaml
├── project-b.yaml
├── k8s-ops.yaml
└── monitoring.yaml

For Large Collections (20+ configs)

Group by category:

~/.tmuxp/
├── dev/
│   ├── webapp.yaml
│   └── api.yaml
├── infra/
│   ├── terraform.yaml
│   └── k8s-ops.yaml
├── client-name/
│   ├── project-a.yaml
│   └── project-b.yaml
└── monitoring.yaml

Load grouped configs: tmuxp load infra/k8s-ops.yaml

Version Control

Store configs in a dotfiles repo managed by GNU Stow or similar:

dotfiles/
└── tmuxp/
    └── .tmuxp/
        ├── project.yaml
        └── ...

---

Common Pitfalls

tmuxp Workflow Patterns

Table of Contents

1. Development Workflow 2. Infrastructure / DevOps Workflow 3. Monitoring Dashboard 4. AI-Assisted Development 5. Multi-Environment Kubernetes 6. CI/CD Pipeline Management 7. Database Operations

---

Development Workflow

Standard software development setup: editor, server, tests, git.

session_name: myapp-dev
start_directory: ~/Projects/myapp

windows:
  - window_name: editor
    focus: true
    layout: main-vertical
    options:
      main-pane-width: 70%
    panes:
      - focus: true
        shell_command:
          - vim .
      - shell_command:
          - npm test -- --watch
      - shell_command:
          - watch -n 5 "git status -sb && echo '' && git log --oneline -5"

  - window_name: server
    layout: even-horizontal
    panes:
      - shell_command:
          - npm run dev
      - shell_command:
          - tail -f logs/dev.log 2>/dev/null || echo "No log file yet"

  - window_name: terminal
    panes:
      - shell_command:
          - echo "Ready for commands"

When to use: Any project with a dev server, test suite, and editor.

---

Infrastructure / DevOps Workflow

Terraform, cloud resources, and infrastructure management.

session_name: infra-project
start_directory: ~/Repos/infrastructure
environment:
  CLOUD_PROVIDER: azure
  RESOURCE_GROUP: rg-myproject
  TF_WORKSPACE: dev

before_script: |
  echo "Checking prerequisites..."
  for tool in terraform az kubectl helm; do
    command -v $tool >/dev/null || echo "Warning: $tool not found"
  done
  az account show >/dev/null 2>&1 || echo "Warning: Not logged into Azure"

windows:
  - window_name: terraform
    focus: true
    layout: main-horizontal
    options:
      main-pane-height: 70%
    panes:
      - focus: true
        shell_command:
          - echo "Terraform Workspace: ${TF_WORKSPACE}"
          - terraform workspace list 2>/dev/null || echo "Not initialized"
      - shell_command:
          - echo "Plan/Apply output will appear here"

  - window_name: cloud-resources
    layout: even-horizontal
    panes:
      - shell_command:
          - az resource list -g ${RESOURCE_GROUP} -o table 2>/dev/null || echo "No resources"
      - shell_command:
          - echo "Resource management pane"

  - window_name: monitoring
    layout: tiled
    panes:
      - htop || top
      - shell_command:
          - kubectl top nodes 2>/dev/null || echo "No cluster connected"
      - shell_command:
          - docker stats --no-stream 2>/dev/null || echo "Docker not running"

When to use: Managing cloud infrastructure, Terraform plans, resource lifecycle.

---

Monitoring Dashboard

Real-time system and application monitoring.

session_name: monitoring
environment:
  K8S_NAMESPACE: default

windows:
  - window_name: system
    layout: tiled
    panes:
      - htop || top
      - shell_command:
          - docker stats 2>/dev/null || echo "Docker not running"
      - shell_command:
          - watch -n 5 "df -h | head -10"
      - shell_command:
          - watch -n 2 "free -h"

  - window_name: kubernetes
    layout: tiled
    panes:
      - shell_command:
          - watch -n 5 "kubectl get pods -n ${K8S_NAMESPACE} 2>/dev/null"
      - shell_command:
          - kubectl get events -n ${K8S_NAMESPACE} --sort-by='.lastTimestamp' -w 2>/dev/null || echo "No cluster"
      - shell_command:
          - watch -n 10 "kubectl top nodes 2>/dev/null"
      - shell_command:
          - watch -n 10 "kubectl top pods -n ${K8S_NAMESPACE} 2>/dev/null"

  - window_name: logs
    layout: even-vertical
    panes:
      - shell_command:
          - if command -v stern >/dev/null; then
              stern -n ${K8S_NAMESPACE} ".*"
            else
              kubectl logs -n ${K8S_NAMESPACE} -f --tail=50 --prefix=true 2>/dev/null || echo "No pods"
            fi
      - shell_command:
          - kubectl get events --all-namespaces --field-selector type=Warning --sort-by='.lastTimestamp' 2>/dev/null | tail -20

When to use: Oncall, incident investigation, system health checks.

---

AI-Assisted Development

Workspace with AI coding agents alongside traditional tools.

session_name: ai-dev
start_directory: ~/Projects/myapp

windows:
  - window_name: ai-agent
    focus: true
    layout: main-horizontal
    options:
      main-pane-height: 70%
    panes:
      - focus: true
        shell_command:
          - echo "AI Agent workspace"
          - claude
      - shell_command:
          - echo "Validation pane (run tests, check output)"

  - window_name: code-review
    panes:
      - shell_command:
          - echo "Code review and git operations"
          - git status

  - window_name: docs
    layout: even-horizontal
    panes:
      - shell_command:
          - echo "Documentation reference"
      - shell_command:
          - echo "Notes and scratch"

When to use: Working with Claude Code, GitHub Copilot, or other AI agents.

---

Multi-Environment Kubernetes

Separate windows per environment with increasing safety.

session_name: k8s-ops
environment:
  APP_NS: myapp
  K8S_CTX_DEV: aks-myapp-dev
  K8S_CTX_STG: aks-myapp-stg
  K8S_CTX_PRD: aks-myapp-prd

before_script: |
  for env in dev stg prd; do
    CTX_VAR="K8S_CTX_${env^^}"
    CTX="${!CTX_VAR}"
    kubectl config get-contexts -o name | grep -q "^${CTX}$" \
      && echo "OK: $CTX" || echo "MISSING: $CTX"
  done

windows:
  - window_name: k8s-dev
    focus: true
    layout: main-horizontal
    options:
      main-pane-height: 65%
    panes:
      - focus: true
        shell_command:
          - kubectl config use-context ${K8S_CTX_DEV}
          - echo "DEV - Full access"
      - shell_command:
          - watch -n 2 "kubectl get pods -n ${APP_NS}"

  - window_name: k8s-staging
    layout: even-vertical
    panes:
      - shell_command:
          - echo "STAGING - Be careful with changes"
          - kubectl config use-context ${K8S_CTX_STG}
      - shell_command:
          - watch -n 5 "kubectl get pods -n ${APP_NS}"

  - window_name: k8s-prod
    layout: even-vertical
    panes:
      - shell_command:
          - echo "PRODUCTION - READ-ONLY"
          - echo "DO NOT use: apply, delete, edit, patch, scale"
          - kubectl config use-context ${K8S_CTX_PRD}
          - k9s --readonly
      - shell_command:
          - watch -n 30 "kubectl top pods -n ${APP_NS} 2>/dev/null"

When to use: Managing Kubernetes across dev/staging/production.

---

CI/CD Pipeline Management

Monitor and manage CI/CD pipelines.

session_name: cicd-ops

windows:
  - window_name: pipelines
    focus: true
    layout: main-horizontal
    options:
      main-pane-height: 70%
    panes:
      - focus: true
        shell_command:
          - echo "Pipeline management"
          - echo "gh run list / az pipelines runs list"
      - shell_command:
          - echo "Build logs will appear here"

  - window_name: artifacts
    layout: even-horizontal
    panes:
      - shell_command:
          - echo "Docker images and artifacts"
          - docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | head -20
      - shell_command:
          - echo "Registry operations"

  - window_name: deploy
    panes:
      - shell_command:
          - echo "Deployment operations"
          - echo "ArgoCD / Helm / kubectl"

When to use: Managing CI/CD pipelines, reviewing builds, deploying releases.

---

Database Operations

Database management and migration workflows.

session_name: db-ops
environment:
  DB_HOST_DEV: localhost
  DB_NAME: myapp_dev

windows:
  - window_name: db-console
    focus: true
    layout: main-vertical
    options:
      main-pane-width: 60%
    panes:
      - focus: true
        shell_command:
          - echo "Database console"
          - echo "psql / mysql / mongosh"
      - shell_command:
          - echo "Migration management"
          - echo "make db-migrate / alembic upgrade head"

  - window_name: db-monitoring
    layout: even-horizontal
    panes:
      - shell_command:
          - echo "Connection monitoring"
      - shell_command:
          - echo "Query performance"

When to use: Database administration, migrations, performance tuning.