カスタムコマンドとアクション
cmux.json は、cmux に自分なりの作業手順を覚えさせる場所です。よく実行するシェルコマンド、ターミナルとブラウザがあらかじめ配置された状態で開くワークスペース、ショートカットやタブバーのボタン、Command Palette に割り当てられるアクションを定義できます。プロジェクト内の .cmux/cmux.json、すべてのプロジェクト向けの ~/.config/cmux/cmux.json、またはその両方に置いてください。
cmux が cmux.json を読み込む場所
項目はプロジェクトのファイル、ユーザー全体のファイル、またはその両方から読み込めます。プロジェクトのファイルについては、cmux は現在のディレクトリから探し始め、その上にある親ディレクトリも順に確認します。
- プロジェクト:
./.cmux/cmux.json(作業ディレクトリから上方向に探して見つけます。ユーザー全体のファイルより優先されます) - フォールバックローカル:
./cmux.json(既存のリポジトリ向けに引き続きサポートされています) - ユーザー全体:
~/.config/cmux/cmux.json(すべてのプロジェクトで共有され、プロジェクトのファイルで定義されていない部分を補います)
cmux.json を編集したら Cmd+Shift+, を押すか、cmux reload-config を実行して変更を適用します。
シェルコマンド
最小の項目は、名前とコマンド文字列だけです。Command Palette でこれを選ぶと、その文字列がフォーカス中のターミナルに入力され、実行されます。
{
"commands": [
{
"name": "Format Changed Files",
"description": "Run the formatter on files that differ from main",
"keywords": [
"fmt",
"prettier",
"style"
],
"command": "git diff --name-only main -- '*.ts' '*.tsx' | xargs npx prettier --write"
},
{
"name": "Reset Local Database",
"keywords": [
"db",
"wipe"
],
"command": "cd \"$(git rev-parse --show-toplevel)\" && ./scripts/db-reset.sh",
"confirm": true
}
]
}シェルコマンドのフィールド
name: Command Palette で選ぶための必須のラベル（空欄不可）command: cmux がフォーカス中のターミナルに入力して実行するシェルのテキストdescription: 項目と並べて表示される任意の補足テキストkeywords: Command Palette で検索したときにこの項目にマッチさせたい追加の語confirm: true にすると、実行前に毎回確認プロンプトが表示されます
シェルコマンドは、フォーカス中のターミナルがその時点でいる場所で実行されます。決まった場所から始める必要がある場合は、コマンドの先頭に cd "$(git rev-parse --show-toplevel)" && を付けて Git リポジトリの最上位へ移動するか、 cd /some/folder && を付けて固定のフォルダーから始めます。
ワークスペースを開くコマンド
コマンドにコマンド文字列の代わりに workspace オブジェクトを指定すると、新しいワークスペースを開くコマンドになります。ワークスペースは、ターミナルとブラウザを収めた分割ペインのツリーとして配置されます。各項目にはこの 2 つのうちどちらか 1 つだけが必要です。
{
"commands": [
{
"name": "API Stack",
"keywords": [
"api",
"server",
"logs"
],
"restart": "confirm",
"workspace": {
"name": "API",
"cwd": "./services/api",
"color": "#10b981",
"env": {
"PORT": "8080"
},
"layout": {
"direction": "vertical",
"split": 0.65,
"children": [
{
"direction": "horizontal",
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Server",
"command": "go run ./cmd/api",
"focus": true
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Worker",
"command": "go run ./cmd/worker",
"env": {
"QUEUE": "default"
}
}
]
}
}
]
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Logs",
"cwd": "/var/log",
"command": "tail -F system.log"
},
{
"type": "browser",
"name": "Health",
"url": "http://localhost:8080/healthz"
}
]
}
}
]
}
}
}
]
}workspace オブジェクトのフィールド
name: ワークスペースのタイトル。省略するとコマンド名が使われますcwd: ワークスペースの基準ディレクトリ。各タブの cwd はここを基準に解決されますlayout: 下で説明するレイアウトツリーのルートノードcolor: サイドバーでの色。#RRGGBB 形式の 16 進数か、ワークスペースの色名で指定しますenv: ワークスペース内のすべてのシェルに引き継がれる環境変数setup: ワークスペースの最初のターミナルに、そのターミナル自身のコマンドより先に送信されるブートストラップコマンド
ワークスペースがすでに開いている場合
コマンドに restart を設定すると、同じ名前のワークスペースがすでに存在するときの動作を決められます:
"new": 新しいワークスペースを作成する (デフォルト)"confirm": まず確認し、同意したら置き換える"recreate": 確認せずにすぐ置き換える"ignore": 既存のワークスペースに切り替える
レイアウトの記述
レイアウトはツリー構造です。内側の各ノードは自分の領域を 2 つに分割し、各リーフはタブを持つペインです。
分割ノード
分割は自分の領域を 2 つに分けます:
direction:"horizontal"または"vertical"children: ちょうど 2 つのノードからなる配列。各ノードは別の分割またはペインですsplit: 区切り線の位置を領域に対する比率で指定します。デフォルトは 0.5 で、0.1〜0.9 の範囲外の値はその範囲に収められます
ペインノード
ペインはツリーのリーフです。surfaces 配列には最初に開くタブを並べ、少なくとも 1 つの項目が必要です。
サーフェス
ペインの surfaces 配列の各項目は、ターミナルかブラウザのタブを 1 つ開きます:
type:"terminal"または"browser"name: デフォルトの代わりに表示するタブのタイトルfocus: true にすると、レイアウトの構築後にこのタブにキーボードフォーカスを移しますcommand: ターミナルのみ: ターミナルが開いた直後に実行するシェルのテキストurl: ブラウザのみ: 読み込むページcwd: このタブの開始ディレクトリ。下記のルールで解決されますenv: 追加する環境変数の名前と値を持つオブジェクト
cwd の値の解決方法
~/path: ホームフォルダー内で解決されます- / で始まるパス: そのまま使われます
./subdir: ワークスペースのディレクトリの後ろに連結されます.または 未設定: ワークスペースのディレクトリを引き継ぎます
ファイルの構造
actions、shortcut、ui.surfaceTabBar.buttons を使う前に最新の nightly ビルドをインストールしてください。commands は引き続き、再利用可能なシェルコマンドとワークスペースレイアウトを定義します。nightly ビルドでは actions レジストリが追加されます。アクションは、サーフェスタブバー、Command Palette、アクション単位のショートカットで共有される公開 ID です。
{
"actions": {
"cmux.newTerminal": {
"type": "agent",
"agent": "claude",
"title": "Claude Code",
"subtitle": "Start Claude Code in a new tab"
},
"lint": {
"type": "command",
"title": "Lint",
"subtitle": "Run the linter in a fresh tab",
"keywords": [
"eslint",
"check"
],
"command": "npm run lint",
"shortcut": [
"cmd+k",
"cmd+l"
],
"icon": {
"type": "symbol",
"name": "checkmark.seal"
}
},
"scratch-dir": {
"type": "command",
"title": "Scratch Directory",
"command": "cd \"$(mktemp -d)\"",
"target": "currentTerminal",
"palette": false,
"icon": {
"type": "emoji",
"value": "📝",
"scale": 0.85
}
},
"api-stack": {
"type": "workspaceCommand",
"title": "API Stack",
"commandName": "API Stack"
}
},
"ui": {
"surfaceTabBar": {
"buttons": [
"cmux.newTerminal",
"cmux.splitRight",
"lint",
{
"action": "scratch-dir",
"tooltip": "cd into a new temp folder"
}
]
}
},
"commands": [
{
"name": "API Stack",
"keywords": [
"api"
],
"workspace": {
"cwd": "./services/api",
"layout": {
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Server",
"command": "go run ./cmd/api"
}
]
}
}
}
}
]
}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 に設定します。
アクションの種類
"command": ターミナルでシェルテキストを実行します。target で現在のターミナルまたは現在のペイン内の新しいタブを選びます。"agent": コーディングエージェントを新しいターミナルタブで起動します。任意の CLI 名(claude、codex、opencode、独自バイナリなど)を指定でき、args も併用できます。"builtin": cmux.newTerminal、cmux.newBrowser、cmux.splitRight、cmux.splitDown などの組み込み cmux アクションに別名を付けます。 コピー用のビルトイン: cmux.copyWorkingDirectory はターミナルの作業ディレクトリを、cmux.copyProjectRoot は Git リポジトリのルート（リポジトリ外では作業ディレクトリ）を、cmux.copyScreen は表示中の画面をコピーします。 SSH、クラウド、リモート tmux のワークスペースでは、リモート側の Git リポジトリを cmux が調べられないため、cmux.copyProjectRoot はリモートの作業ディレクトリをコピーします。"workspaceCommand": commands から名前付きのワークスペース定義を実行します。複数ペインのレイアウト、カスタム作業ディレクトリ、起動コマンドに使います。"workspace": アクション内に埋め込んだワークスペース定義から新しいワークスペースを作成します。restart の指定も可能で、新規ワークスペースのプラスボタンメニューに自動的に表示されます。"setting": グローバルの cmux.json の設定を 1 つ変更します。たとえば true/false の設定を切り替えたり、値のリストを順に切り替えたりできます。詳しくは下の「設定アクション」を参照してください。"settingPreset": settingPresets に登録した名前付きの設定グループをまとめて適用します。
アクションのフィールド
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: アクションを実行する前に確認します。newWorkspaceMenu: true にすると任意のアクションを新規ワークスペースのプラスボタンメニューに表示し、false にするとワークスペースアクションを非表示にします。
Command Palette の動作
Command Palette は解決済みのアクションレジストリを読みます。palette が false でない場合、カスタムアクション ID は行として追加されます。従来の commands は、同じ生成 ID のアクションが既にない限り、自動的にカスタム行として追加されます。組み込みコマンドは通常のパレット表示名を保ちますが、cmux.newTerminal のような組み込み ID を上書きすると、その共有エントリポイントの動作が変わります。
設定アクション
設定アクションには設定の path と、次のうち 1 つだけを指定します: set(値を書き込む)、toggle: true(true/false の設定を切り替える)、cycle(リスト内の次の値に進み、最後まで来たら先頭に戻る)、unset: true(cmux.json からキーを削除し、設定ウインドウで選んだ値か既定値に戻す)。toggle と cycle は、設定ウインドウで変更した値を含め、cmux が現在使っている値から始まります。settingPreset アクションは settingPresets のエントリを適用します。エントリは部分的な cmux.json で、入れ子のオブジェクトはキーごとにマージされます。cmux は保存前にすべての変更をスキーマで検証し、コメントや他のキーはそのまま残して、変更をすぐに反映します。設定アクションとプリセットはグローバルの cmux.json と、そこから参照するパックからのみ実行でき、プロジェクトの設定では宣言できません。
{
"actions": {
"scroll.cycle": {
"type": "setting",
"title": "Cycle Scroll Speed",
"path": "terminal.scrollSpeed",
"cycle": [1.0, 1.4, 1.8]
},
"editor.wrap": {
"type": "setting",
"title": "Toggle Editor Word Wrap",
"path": "fileEditor.wordWrap",
"toggle": true
},
"sidebar.quiet": {
"type": "settingPreset",
"title": "Quiet Sidebar",
"preset": "sidebar.quiet"
}
},
"settingPresets": {
"sidebar.quiet": {
"sidebar": { "showPorts": false, "showPullRequests": false, "showLog": false }
}
}
}同じ変更はターミナルからも行えます: cmux config set terminal.scrollSpeed 1.4、cmux config toggle fileEditor.wordWrap、cmux config preset sidebar.quiet。
confirm: true を指定すると、cmux は保存前に確認し、同じ変更を行う cmux config コマンドを表示します。パスはすべての "." で分割されるため、キー自体に "." を含むもの(~/src/app.web 用の workspaceGroups.byCwd エントリなど)はこの方法では変更できません。cmux.json で直接編集してください。
プラスボタンのカスタムアクション
ui.newWorkspace.action でプラスボタンの動作を上書きします。ui.newWorkspace.contextMenu (または別名 rightClick) で、右クリックメニューの順序を定義します。メニュー項目には、アクション ID、アクションオブジェクト、または { "type": "separator" } を指定できます。 未設定の場合、メニューには cmux.newWorkspace (⌘N), cmux.newCloudWorkspace (⌘Y), cmux.newCloudMachine (⇧⌘Y), cmux.newTerminal (⌘T), cmux.newBrowser (⇧⌘L) が現在のショートカットとともに表示されます。新しい Cloud ワークスペースは最後に選択した Cloud ワークスペースのマシン、次に右側サイドバーの先頭のマシンを使い、利用できるマシンがなければ New Cloud Machine を開きます。New Cloud Machine はマシンを明示的に作成します。クラウドの項目は Cloud Machines が有効な場合のみ表示されます。
{
"actions": {
"worktree-agents": {
"type": "workspaceCommand",
"title": "Agents in New Worktree",
"commandName": "Agents in New Worktree",
"icon": {
"type": "symbol",
"name": "arrow.triangle.branch"
}
}
},
"ui": {
"newWorkspace": {
"action": "worktree-agents",
"contextMenu": [
"worktree-agents",
{
"type": "separator"
},
{
"action": "cmux.newWorkspace",
"title": "Blank Workspace"
},
{
"action": "cmux.newBrowser",
"title": "Browser"
}
]
}
},
"commands": [
{
"name": "Agents in New Worktree",
"description": "Branch off a new Git worktree, then run Codex and Claude Code in it side by side",
"workspace": {
"name": "Worktree",
"layout": {
"direction": "vertical",
"split": 0.7,
"children": [
{
"direction": "horizontal",
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Codex",
"command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; echo \"Waiting for the worktree...\"; until [ -s \"$marker\" ]; do sleep 0.25; done; cd \"$(cat \"$marker\")\" && exec codex --yolo"
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Claude",
"command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; echo \"Waiting for the worktree...\"; until [ -s \"$marker\" ]; do sleep 0.25; done; cd \"$(cat \"$marker\")\" && exec claude --dangerously-skip-permissions"
}
]
}
}
]
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Setup",
"command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; rm -f \"$marker\"; root=$(git rev-parse --show-toplevel) || exit 1; branch=\"wt-$(date +%m%d-%H%M%S)\"; wt=\"$root/../$(basename \"$root\")-$branch\"; git -C \"$root\" worktree add -b \"$branch\" \"$wt\" && printf \"%s\\n\" \"$wt\" > \"$marker\" && cd \"$wt\" && exec \"${SHELL:-/bin/zsh}\" -l",
"focus": true
}
]
}
}
]
}
}
}
]
}この例では、通常のプラスクリックで worktree-agents アクションを実行します。commands のワークスペースコマンドは、見えるセットアップ用ターミナルを使って最初に Git worktree を作成します。Codex と Claude は同時に起動し、ワークスペース固有の状態ファイルを待ってから、作成されたディレクトリへ cd して exec します。
ワークスペースレイアウト
ワークスペースレイアウトは workspace アクションとして保存され、ワークスペース定義をアクション内に直接埋め込むため、別途 commands エントリは不要です。ワークスペースと同じフィールドに加えて、最初のターミナルにそのターミナル自身のコマンドより先に送信されるブートストラップコマンド setup をサポートします:
{
"actions": {
"pair-review": {
"type": "workspace",
"title": "Pair Review",
"icon": {
"type": "symbol",
"name": "person.2.wave.2"
},
"restart": "ignore",
"newWorkspaceMenu": true,
"workspace": {
"name": "Review",
"cwd": "~/src/app",
"setup": "git pull --ff-only",
"layout": {
"direction": "horizontal",
"split": 0.55,
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Diff",
"command": "git log -p -n 5",
"focus": true
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Codex",
"command": "codex"
},
{
"type": "terminal",
"name": "Shell"
}
]
}
}
]
}
}
}
}
}ワークスペースレイアウトはプラスボタンの右クリックメニューに自動的に表示されます。newWorkspaceMenu を false にすると非表示にでき、他のアクションで true にするとメニューに追加できます。
JSON を書かずに作成することもできます。プラスボタンを右クリックして ワークスペースをレイアウトとして保存 を選ぶと、現在のワークスペースの分割、ディレクトリ、実行中のエージェント、ブラウザタブが ~/.config/cmux/cmux.json に保存されます。これは actions ブロックのエントリとして保存されます。ワークスペースレイアウトをカスタマイズ はそのファイルをエディタで開きます。
新規ワークスペースのデフォルト
新規ワークスペースのデフォルト サブメニューで、通常の新規ワークスペース作成時に実行する保存済みワークスペースレイアウトを選べます。「なし」を選ぶと空のターミナルに戻ります。保存ダイアログにも 新規ワークスペースのデフォルトとして使用 チェックボックスがあります。設定キーは ui.newWorkspace.action です。プロジェクトローカルの .cmux/cmux.json の値は ~/.config/cmux/cmux.json より優先されます。
完全な例
{
"actions": {
"cmux.newTerminal": {
"type": "command",
"title": "Codex",
"command": "codex --yolo",
"shortcut": "cmd+t",
"icon": {
"type": "image",
"path": "./icons/codex.svg"
}
},
"review": {
"type": "agent",
"agent": "claude",
"args": "--permission-mode plan",
"title": "Plan with Claude",
"shortcut": "cmd+shift+p",
"icon": {
"type": "symbol",
"name": "list.bullet.clipboard"
}
},
"storybook": {
"type": "workspaceCommand",
"commandName": "Storybook",
"newWorkspaceMenu": true
},
"typecheck": {
"type": "command",
"title": "Typecheck",
"command": "npx tsc --noEmit",
"target": "newTabInCurrentPane",
"confirm": false,
"icon": {
"type": "emoji",
"value": "🔎"
}
}
},
"ui": {
"surfaceTabBar": {
"buttons": [
"cmux.newTerminal",
"review",
{
"action": "typecheck",
"title": "tsc"
},
"cmux.newBrowser",
"cmux.splitDown"
]
},
"newWorkspace": {
"contextMenu": [
"storybook",
{
"type": "separator"
},
"cmux.newTerminal",
"cmux.newBrowser"
]
}
},
"commands": [
{
"name": "Storybook",
"description": "Component explorer with a live preview beside it",
"keywords": [
"ui",
"components",
"stories"
],
"workspace": {
"name": "Storybook",
"cwd": "./packages/ui",
"color": "#a855f7",
"layout": {
"direction": "horizontal",
"split": 0.4,
"children": [
{
"direction": "vertical",
"split": 0.5,
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Storybook",
"command": "npx storybook dev -p 6006 --no-open",
"focus": true
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Tests",
"command": "npx vitest --watch",
"env": {
"CI": "false"
}
}
]
}
}
]
},
{
"pane": {
"surfaces": [
{
"type": "browser",
"name": "Preview",
"url": "http://localhost:6006"
}
]
}
}
]
}
}
},
{
"name": "Install Dependencies",
"keywords": [
"install",
"deps"
],
"command": "npm ci",
"confirm": true
},
{
"name": "Open Changelog",
"keywords": [
"changes",
"release"
],
"command": "${EDITOR:-vi} CHANGELOG.md"
}
]
}