カスタムコマンド：CMUXにワークフローを覚えさせる

仕事を始めるたびに毎回同じことをしていないだろうか：npm run devを実行するペインを開き、プレビューブラウザを開くために切り替え、手元に置いておく別のシェルを開く？毎日3分が消えていく。

CMUXカスタムコマンドはまさにこれを解決するために作られた。cmux.jsonに固定の作業環境を定義し、1つのコマンドでworkspaceレイアウト全体を復元する。

cmux.jsonの場所

プロジェクトのルートディレクトリにcmux.jsonを作成する。CMUXが自動的に読み込み、内部で定義されたコマンドを利用可能なコマンドリストに追加する。

2つのコマンドタイプ

Workspaceコマンド：CMUXを開き、事前定義されたレイアウトでworkspaceを作成する — ターミナル、ブラウザ、分割設定が全て事前に指定される。「1日の開始」シナリオに最適。

シンプルコマンド：workspaceを作成せずにシェルコマンドを実行する。「テストを実行」や「環境を初期化」のような1回限りの操作に適している。

Workspaceコマンド：開発環境を定義する

完全な例 — Next.js devサーバー、ブラウザプレビュー、バックアップシェルを一度に開く1つのコマンド：

{
  "commands": [
    {
      "name": "Web Dev",
      "description": "Next.jsを起動してプレビューを開く",
      "keywords": ["web", "docs", "next", "frontend"],
      "restart": "confirm",
      "workspace": {
        "name": "Web Dev",
        "cwd": "./web",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Next.js",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "プレビュー",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

設定の解説：

name / description：コマンドリストに表示されるラベルと説明
keywords：検索に使用 — キーワードを入力してこのコマンドを見つける
restart：workspaceが既に存在する場合、"confirm"は再起動するか確認する；"ignore"はスキップする
workspace.cwd：このworkspaceのデフォルト作業ディレクトリ
workspace.color：サイドバーでのこのworkspaceの識別色
layout：完全なレイアウト構造を定義する

レイアウトの論理：directionは分割方向（"horizontal"で左右、"vertical"で上下）、splitは分割比率（0.5は均等二分）、childrenにペインが含まれる。

この例が作るもの：左半分にNext.js、右上にブラウザプレビュー、右下にバックアップシェル。

シンプルコマンド：1回限りの操作

レイアウトが不要な操作に：

{
  "name": "セットアップ",
  "description": "サブモジュールを初期化してビルド依存関係をインストール",
  "keywords": ["setup", "init", "install"],
  "command": "./scripts/setup.sh",
  "confirm": true
}

confirm: trueは実行前に確認プロンプトを表示する — 破壊的な操作（キャッシュのクリア、依存関係の再インストール）に適切。

{
  "name": "ユニットテスト実行",
  "keywords": ["test", "unit"],
  "command": "./scripts/test-unit.sh",
  "confirm": true
}

ログ監視Workspace

もう1つの一般的なパターン — バックグラウンドで常時実行するログ監視専用のworkspace：

{
  "name": "デバッグログ",
  "description": "リアルタイムデバッグイベントログ監視",
  "keywords": ["log", "debug", "tail"],
  "restart": "ignore",
  "workspace": {
    "name": "デバッグログ",
    "layout": {
      "direction": "horizontal",
      "split": 0.5,
      "children": [
        {
          "pane": {
            "surfaces": [
              {
                "type": "terminal",
                "name": "イベント",
                "command": "tail -f /tmp/app-debug.log",
                "focus": true
              }
            ]
          }
        },
        {
          "pane": {
            "surfaces": [
              {
                "type": "terminal",
                "name": "Shell"
              }
            ]
          }
        }
      ]
    }
  }
}

restart: "ignore"の論理：このworkspaceが既に実行中なら、そのままにする — 監視を続けさせる。

いくつかの設計原則

キーワードを慎重に考える：コマンドが多くなったとき、keywordsが素早く見つける唯一の方法になる。["start", "dev", "run"]のような自然に入力するであろう動詞を含める。

cwdには相対パスを使う：./webは/Users/yourname/projects/app/webより良い — 設定を変更せずに異なるマシンで動作する。

カラーでカテゴリ分けする：異なるworkspaceタイプに異なる色を付ける — 開発は青、テストはオレンジ、監視はグレー。サイドバーを一目見るだけで全てがわかる。

カスタムコマンドの設定が終わった。最終記事では全てをまとめて実際のマルチエージェントワークフローに適用する：実際のマルチエージェントワークフロー：実開発のためのCMUXパターン。