カスタムコマンド

プロジェクトでは .cmux/cmux.json、グローバルでは ~/.config/cmux/cmux.json を使ってアクション、カスタムコマンド、ワークスペースレイアウトを定義します。アクションはサーフェスタブバーやコマンドパレットに表示できます。

ファイルの場所

cmux は2か所で設定を検索します：

プロジェクトごと： ./.cmux/cmux.json - プロジェクトディレクトリに置かれ、優先されます
フォールバックローカル: ./cmux.json - 既存のリポジトリ向けに引き続きサポートされています
グローバル: ~/.config/cmux/cmux.json - すべてのプロジェクトに適用され、ローカルで未定義のコマンドを補完します

ローカルのアクションとコマンドは、同じ ID または名前を持つグローバル項目を上書きします。

アクションレジストリは nightly 機能です。actions、shortcut、ui.surfaceTabBar.buttons を使う前に最新の nightly ビルドをインストールしてください。

プロジェクトローカルのアクションは、サーフェスタブバーと Command Palette にすぐ表示されます。初回実行時は引き続き信頼確認が出ます。信頼はリポジトリ単位ではなく、完全一致するアクションのフィンガープリント単位です。プロジェクトローカルの画像アイコンは、そのアクションを信頼するまでロックされたままです。

プロジェクト設定またはグローバル設定にスキーマエラーがある場合、cmux は次に有効な設定へフォールバックし、Command Palette に cmux.json Schema Error 行を表示します。選択すると設定ファイルを開けます。

cmux.json を編集したら Cmd+Shift+, を押すか、cmux reload-config を実行して変更を適用します。

スキーマ

commands は引き続き、再利用可能なシェルコマンドとワークスペースレイアウトを定義します。nightly ビルドでは actions レジストリが追加されます。アクションは、サーフェスタブバー、Command Palette、アクション単位のショートカットで共有される公開 ID です。

cmux.json

{
  "actions": {
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "subtitle": "Open Codex in a new terminal tab",
      "command": "codex --dangerously-bypass-approvals-and-sandbox",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+t",
      "icon": { "type": "image", "path": "./icons/codex.svg" }
    },
    "claude": {
      "type": "command",
      "title": "Claude Code",
      "command": "claude --dangerously-skip-permissions",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+shift+c",
      "icon": { "type": "image", "path": "./icons/claude.svg" }
    },
    "opencode": {
      "type": "command",
      "title": "OpenCode",
      "command": "opencode",
      "target": "newTabInCurrentPane",
      "palette": false,
      "icon": { "type": "emoji", "value": "🧪", "scale": 0.9 }
    },
    "web-dev": {
      "type": "workspaceCommand",
      "title": "Web Dev",
      "commandName": "Web Dev"
    }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        "cmux.splitRight",
        "cmux.splitDown",
        "claude"
      ]
    }
  },
  "commands": [
    {
      "name": "Web Dev",
      "keywords": ["dev", "start"],
      "workspace": { ... }
    }
  ]
}

nightly アクションレジストリ

actions は安定した ID を実行可能な動作に対応付けます。既定値を上書きするには、組み込み ID の cmux.newTerminal、cmux.newBrowser、cmux.splitRight、cmux.splitDown を使います。プロジェクト固有のツールには独自の ID を使います。

palette は既定で true です。false にすると、サーフェスタブバーやショートカットからは使えるまま、Command Palette には表示しません。shortcut は設定ショートカットと同じ構文を使います。たとえば cmd+shift+c や ["cmd+k", "cmd+c"] です。

ui.surfaceTabBar.buttons がある場合、既定のボタン一覧を置き換えます。組み込み ID を省略すると非表示になります。アイコンは常にオブジェクト形式です: { "type": "symbol", "name": "play.circle" }、{ "type": "emoji", "value": "🧪", "scale": 0.9 }、または { "type": "image", "path": "./icons/codex.svg" }。画像パスは設定ファイルからの相対パスです。絵文字の scale は省略可能で、既定値は 1 です。SVG、PDF、PNG、JPEG、GIF、TIFF、BMP、HEIC、HEIF、WebP、AVIF、ICO、ICNS に対応しています。

各ボタン項目は、アクション ID 文字列またはボタンオブジェクトにできます。同じアクションに別のサーフェスラベル、アイコン、ツールチップを付けたい場合は、ボタンオブジェクトを使います。解決後のボタンタイトルは、信頼確認のタイトルにも使われます。

承認や権限のフラグは、実際に実行したいコマンド文字列へ直接入れてください。既定のアクションターゲットは newTabInCurrentPane です。そのため一般的には、現在のペインに新しいターミナルタブを開き、そこで Codex、Claude Code、OpenCode を起動します。

カスタムアクションと Command Palette

actions の項目は、cmux が実行する再利用可能な処理です。同じ動作を Command Palette、サーフェスタブバー、ショートカット、またはプラスボタンのメニューから使えるようにしたい場合にアクションを使います。再利用可能なシェルコマンドやワークスペースレイアウトには commands を使い続けます。Command Palette に出したくないアクションは palette を false に設定します。

アクションの種類

"builtin": cmux.newTerminal、cmux.newBrowser、cmux.splitRight、cmux.splitDown などの組み込み cmux アクションに別名を付けます。
"command": ターミナルでシェルテキストを実行します。target で現在のターミナルまたは現在のペイン内の新しいタブを選びます。
"agent": 対応しているコーディングエージェントを起動します。現在は codex と claude を、任意の引数付きでサポートしています。
"workspaceCommand": commands から名前付きのワークスペース定義を実行します。複数ペインのレイアウト、カスタム作業ディレクトリ、起動コマンドに使います。

アクションのフィールド

title: Command Palette の行タイトル、サーフェスボタンのラベル、メニュー項目タイトル、信頼確認のタイトルです。項目側で上書きできます。
subtitle / description: Command Palette の補助テキストです。description は subtitle の別名として使えます。
keywords: Command Palette 用の追加検索語です。
palette: カスタムアクションでは既定で true です。false にすると、他からは呼び出せるまま Command Palette から隠せます。
shortcut: 任意のアクションショートカットです。設定ショートカットと同じ単一キーまたは 2 ステップのコード構文を使います。
target: command と agent アクション専用です。currentTerminal または newTabInCurrentPane を使います。
confirm: アクションを実行する前に確認します。

Command Palette の動作

Command Palette は解決済みのアクションレジストリを読みます。palette が false でない場合、カスタムアクション ID は行として追加されます。従来の commands は、同じ生成 ID のアクションが既にない限り、自動的にカスタム行として追加されます。組み込みコマンドは通常のパレット表示名を保ちますが、cmux.newTerminal のような組み込み ID を上書きすると、その共有エントリポイントの動作が変わります。

プラスボタンのカスタムアクション

ui.newWorkspace.action でプラスボタンの動作を上書きします。ui.newWorkspace.contextMenu (または別名 rightClick) で、右クリックメニューの順序を定義します。メニュー項目には、アクション ID、アクションオブジェクト、または { "type": "separator" } を指定できます。

cmux.json

{
  "actions": {
    "worktree-agents": {
      "type": "workspaceCommand",
      "title": "Worktree Agents",
      "commandName": "Worktree Agents",
      "icon": { "type": "symbol", "name": "folder.badge.plus" }
    }
  },
  "ui": {
    "newWorkspace": {
      "action": "worktree-agents",
      "contextMenu": [
        { "action": "worktree-agents", "title": "Worktree Agents" },
        { "type": "separator" },
        { "action": "cmux.newTerminal", "title": "New Terminal" },
        { "action": "cmux.newBrowser", "title": "New Browser" }
      ]
    }
  },
  "commands": [
    {
      "name": "Worktree Agents",
      "description": "Create a fresh Git worktree and start Codex and Claude inside it",
      "workspace": {
        "name": "Worktree Agents",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "split": 0.38,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Worktree",
                    "command": "set -euo pipefail; state=\"${TMPDIR:-/tmp}/cmux-worktree-${CMUX_WORKSPACE_ID:-manual}.dir\"; rm -f \"$state\"; repo=$(git rev-parse --show-toplevel); mkdir -p \"$repo/../worktrees\"; slug=agents-$(date +%Y%m%d-%H%M%S); dir=\"$repo/../worktrees/$slug\"; git -C \"$repo\" worktree add -b \"$slug\" \"$dir\"; printf \"%s\\n\" \"$dir\" > \"$state\"; cd \"$dir\"; exec \"${SHELL:-/bin/zsh}\" -l",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.5,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Codex",
                        "command": "state=\"${TMPDIR:-/tmp}/cmux-worktree-${CMUX_WORKSPACE_ID:-manual}.dir\"; echo \"Waiting for worktree...\"; while [ ! -s \"$state\" ]; do sleep 0.2; done; dir=$(cat \"$state\"); cd \"$dir\"; exec codex --dangerously-bypass-approvals-and-sandbox"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Claude",
                        "command": "state=\"${TMPDIR:-/tmp}/cmux-worktree-${CMUX_WORKSPACE_ID:-manual}.dir\"; echo \"Waiting for worktree...\"; while [ ! -s \"$state\" ]; do sleep 0.2; done; dir=$(cat \"$state\"); cd \"$dir\"; exec claude --dangerously-skip-permissions"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

この例では、通常のプラスクリックで worktree-agents アクションを実行します。commands のワークスペースコマンドは、見えるセットアップ用ターミナルを使って最初に Git worktree を作成します。Codex と Claude は同時に起動し、ワークスペース固有の状態ファイルを待ってから、作成されたディレクトリへ cd して exec します。

シンプルコマンド

シンプルコマンドは現在フォーカスされているターミナルでシェルコマンドを実行します：

cmux.json

{
  "commands": [
    {
      "name": "Run Tests",
      "keywords": ["test", "check"],
      "command": "npm test",
      "confirm": true
    }
  ]
}

フィールド

name: コマンドパレットに表示されます（必須）
description: 任意の説明
keywords: コマンドパレット用の追加検索キーワード
command: フォーカスされたターミナルで実行するシェルコマンド
confirm: 実行前に確認ダイアログを表示する

シンプルコマンドはフォーカスされたターミナルの現在の作業ディレクトリで実行されます。プロジェクト相対パスに依存するコマンドの場合は、先頭に cd "$(git rev-parse --show-toplevel)" && を付けてリポジトリのルートから実行するか、 cd /your/path && で任意のディレクトリを指定できます。

ワークスペースコマンド

ワークスペースコマンドは、分割、ターミナル、ブラウザペインのカスタムレイアウトで新しいワークスペースを作成します：

cmux.json

{
  "commands": [
    {
      "name": "Dev Environment",
      "keywords": ["dev", "fullstack"],
      "workspace": {
        "name": "Dev",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Frontend",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Backend",
                    "command": "cargo watch -x run",
                    "cwd": "./server",
                    "env": { "RUST_LOG": "debug" }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

ワークスペースフィールド

name: ワークスペースのタブ名（デフォルトはコマンド名）
cwd: ワークスペースの作業ディレクトリ
color: ワークスペースのタブカラー
layout: 分割とペインを定義するレイアウトツリー

再起動の動作

同名のワークスペースが既に存在する場合の動作を制御します：

"new": 新しいワークスペースを作成する (デフォルト)
"ignore": 既存のワークスペースに切り替える
"recreate": 確認なしに閉じて再作成する
"confirm": 再作成前にユーザーに確認する

レイアウトツリー

レイアウトツリーは、再帰的な分割ノードを使用してペインの配置を定義します：

分割ノード

スペースを2つの子に分割します：

direction: "horizontal" または "vertical"
split: 分割位置（0.1〜0.9、デフォルト0.5）
children: 正確に2つの子ノード（分割またはペイン）

ペインノード

1つ以上のサーフェス（ペイン内のタブ）を含むリーフノード。

サーフェス定義

ペイン内の各サーフェスはターミナルまたはブラウザです：

type: "terminal" または "browser"
name: カスタムタブタイトル
command: 作成時に自動実行するシェルコマンド（ターミナルのみ）
cwd: このサーフェスの作業ディレクトリ
env: キーと値のペアとしての環境変数
url: 開くURL（ブラウザのみ）
focus: 作成後にこのサーフェスにフォーカスする

作業ディレクトリの解決

. または省略: ワークスペースの作業ディレクトリ
./subdir: ワークスペースの作業ディレクトリからの相対パス
~/path: ホームディレクトリに展開
絶対パス: そのまま使用

完全な例

cmux.json

{
  "actions": {
    "web-dev": { "type": "workspaceCommand", "commandName": "Web Dev" },
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "command": "codex --dangerously-bypass-approvals-and-sandbox",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+t",
      "icon": { "type": "image", "path": "./icons/codex.svg" }
    },
    "claude": {
      "type": "command",
      "title": "Claude Code",
      "command": "claude --dangerously-skip-permissions",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+shift+c",
      "icon": { "type": "image", "path": "./icons/claude.svg" }
    },
    "start-dev": {
      "type": "command",
      "command": "npm run dev",
      "target": "newTabInCurrentPane",
      "icon": { "type": "symbol", "name": "play.circle" }
    }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        "cmux.splitRight",
        "cmux.splitDown",
        {
          "action": "claude",
          "title": "Claude Here"
        },
        "start-dev"
      ]
    }
  },
  "commands": [
    {
      "name": "Web Dev",
      "description": "Docs site with live preview",
      "keywords": ["web", "docs", "next", "frontend"],
      "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": "Preview",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "name": "Debug Log",
      "description": "Tail the debug event log from the running dev app",
      "keywords": ["log", "debug", "tail", "events"],
      "workspace": {
        "name": "Debug Log",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Events",
                    "command": "tail -f /tmp/cmux-debug.log",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Setup",
      "description": "Initialize submodules and build dependencies",
      "keywords": ["setup", "init", "install"],
      "command": "./scripts/setup.sh",
      "confirm": true
    },
    {
      "name": "Reload",
      "description": "Build and launch the debug app tagged to the current branch",
      "keywords": ["reload", "build", "run", "launch"],
      "command": "./scripts/reload.sh --tag $(git branch --show-current)"
    },
    {
      "name": "Run Unit Tests",
      "keywords": ["test", "unit"],
      "command": "./scripts/test-unit.sh",
      "confirm": true
    }
  ]
}