tmux

tmux & tmuxp スキル

tmuxp の YAML 設定を使って、tmux セッションの作成、編集、デバッグ、最適化を行います。

すばやく判断する

タスク	アプローチ
新しいプロジェクト用ワークスペース	テンプレートから tmuxp の YAML を作成
セッションの読み込みエラーを修正	session_name、YAML 構文、ツールの利用可否を確認
複数環境の K8s	環境変数と環境ごとのウィンドウを安全対策とともに使用
シンプルな開発環境	エディター、サーバー、ターミナルの 2～3 個のウィンドウ
複雑なインフラ	before_script による検証、ヘルパースクリプト、監視ウィンドウ
既存のレイアウトを取得	tmuxp freeze を実行してから、出力を整理

セッション名のルール

tmux のセッション名にはピリオド（.）やコロン（:）を含められません。

よくある落とし穴：ユーザー名にピリオドが含まれている場合（例：first.last）に、session_name で ${USER} を使うことです。必ず固定名を使うか、サニタイズしてください：

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

# GOOD - static name
session_name: project-dev

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

設定の構造

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

レイアウト

レイアウト	用途	ペインの配置
main-vertical	エディター＋サイドバー	左側が広く、右側に縦に並ぶ
main-horizontal	ログ＋ステータス	上側が広く、下側が分割される
even-horizontal	横並びで均等に配置	横方向に均等に分割
even-vertical	縦に均等に配置	縦方向に均等に分割
tiled	監視ダッシュボード	ペインを均等なグリッド状に配置

オプションを使ってメインペインのサイズを制御します：

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

実行中のセッションからカスタムレイアウトを取得します：

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

ペインの定義

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:
  # 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}

シークレットをハードコードしないでください。シェルから環境変数を参照します：${AZURE_SUBSCRIPTION_ID}。

before_script による検証

before_script を使って前提条件を検証します。終了コード 1 でセッションの作成が中止されます：

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"

本番環境での安全対策パターン

読み取り専用アクセスと警告によって、本番環境を保護します：

- 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 コマンド

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

トラブルシューティング

エラー	原因	解決方法
BadSessionName: contains periods	session_name に . が含まれている（多くの場合 ${USER} が原因）	${USER} のプレフィックスを削除するか、サニタイズする
BadSessionName: contains colons	session_name に : が含まれている	名前からコロンを削除する
セッションがすでに存在する	session_name が重複している	古いセッションを終了する：tmux kill-session -t name
コマンドが実行されない	シェルとの互換性	まずコマンドを手動でテストする
レイアウトが崩れる	レイアウトに対してターミナルが小さすぎる	定義済みのレイアウトを使うか、tmuxp load -d でテストする
環境変数が展開されない	構文が間違っている	YAML の値では $VAR ではなく ${VAR} を使う

デバッグ：詳細な出力を表示するには tmuxp -v load config.yaml を実行します。

参考資料

• WORKFLOWS.md - よく使われるワークフローパターン（開発、インフラ、監視）
• BEST-PRACTICES.md - 本番環境でのパターン、安全対策、整理方法
• templates/ - すぐに使える設定テンプレート

ワークフロー：新しい設定を作成する

1. プロジェクトの種類（開発、インフラ、監視、混合）を特定する
2. templates/ からテンプレートを選ぶ
3. session_name（ピリオドやコロンを含めない）、start_directory、環境変数を設定する
4. 機能ごとにウィンドウを設計する（エディター、サーバー、ログ、k8s など）
5. 各ウィンドウの用途に合ったレイアウトを選ぶ
6. プロジェクトに外部依存関係がある場合は、before_script による検証を追加する
7. 本番環境にアクセスするウィンドウには安全対策を追加する
8. テストする：tmuxp load -d config.yaml を実行してから tmux attach -t session-name を実行する

---

注意点

• ピリオドを含むセッション名は Unix ソケットのパスで問題を起こします： ${USER} に .（例：first.last）が含まれていると、tmux が /tmp/tmux-UID/ のソケットパスに名前を使用するため、BadSessionName が発生します。固定名を使うか、${USER//\./-} でサニタイズしてください。
• before_script は対話型の zsh ではなく、新しいシェルで実行されます： エイリアス、関数、.zshrc から読み込まれる環境変数は利用できません。command -v は動作しますが、myalias は動作しません。それらに依存する場合は、~/.zshrc を明示的に読み込んでください。
• shell_command_before はウィンドウ内のすべてのペインで実行されます： 時間のかかるコマンド（500ms 以上かかる zsh 設定の読み込み、venv の有効化など）は遅延を増大させます。4 ペインのウィンドウでは、セッションの読み込みに約 2 秒追加されます。1 つのペインでしか必要ない場合は、代わりにペインごとの shell_command を使ってください。
• tmuxp freeze が取得するのは意図ではなく、実行中の状態です： 出力にはランダムな作業ディレクトリ、履歴展開されたコマンド、実際のペインサイズが含まれます。コミットする前に確認して整理してください。フリーズした YAML は出発点であり、完成した設定ではありません。
• 環境変数の展開はペインの起動時ではなく、YAML の読み込み時に行われます： environment: FOO: ${BAR} は、tmuxp load を実行したシェルの $BAR を解決します。そのシェルで $BAR が設定されていない場合、後からペイン内で定義しても空のままです。
• 複数のペインに focus: true を設定すると、最後のものが黙って選ばれます： エラーも警告もなく、実行時にファイルの設定が誤っているように見えるだけです。デバッグを始める前に、ウィンドウごとに grep -c "focus: true" で検証してください。