自訂命令與動作
cmux.json 是讓 cmux 學會你自己工作流程的地方：經常執行的 shell 命令、開啟時就依預設排好終端機和瀏覽器的工作區，以及可以綁定到快速鍵、分頁列按鈕和 Command Palette 的動作。可以放在專案內的 .cmux/cmux.json、適用於所有專案的 ~/.config/cmux/cmux.json，或兩處都放。
cmux 從哪裡讀取 cmux.json
項目可以來自專案檔案、使用者層級檔案，或兩者同時提供。對於專案檔案，cmux 會從目前目錄開始尋找，並逐一檢查其上方的每一層上層目錄。
- 專案層級：
./.cmux/cmux.json(從工作目錄往上尋找而得；優先於使用者層級檔案) - 本機回退:
./cmux.json(仍支援現有 repo) - 使用者層級：
~/.config/cmux/cmux.json(由所有專案共用；補上專案檔案中未定義的內容)
編輯 cmux.json 後，按 Cmd+Shift+, 或執行 cmux reload-config 來套用變更。
shell 命令
最簡單的項目只需一個名稱和一個命令字串。在 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
}
]
}shell 命令欄位
name: 必填且不可空白的標籤，用於在 Command Palette 中選取command: cmux 輸入到目前聚焦的終端機並執行的 shell 文字description: 選用的次要文字，顯示在項目旁邊keywords: 在 Command Palette 中搜尋時也應符合此項目的其他字詞confirm: 設為 true 後，每次執行前都會顯示確認提示
shell 命令會在目前聚焦的終端機所在位置執行。如果命令需要確定的起始位置，可以在開頭加上 cd "$(git rev-parse --show-toplevel)" && 來移至 Git 儲存庫的最上層，或加上 cd /some/folder && 固定在某個資料夾。
開啟工作區的命令
為命令提供 workspace 物件來取代命令字串，它就會改為開啟一個新的工作區，排列成一棵由分割窗格組成的樹，內含終端機和瀏覽器。每個項目必須且只能包含兩者之一。
{
"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 十六進位值或工作區顏色名稱env: Environment variables inherited by every shell in the workspacesetup: Bootstrap command sent to the workspace's first terminal before that terminal's own command
當工作區已經開啟時
在命令上設定 restart，決定已有同名工作區時的行為：
"new": 建立新的 workspace（預設）"confirm": 先詢問，你同意後再取代"recreate": 不詢問，立即取代"ignore": 切換至現有 workspace
描述配置
配置是一棵樹。每個內部節點會把自己的區域一分為二，每個葉節點都是一個容納分頁的窗格。
分割節點
分割會把自己的區域分成兩部分：
direction:"horizontal"或"vertical"children: 剛好包含兩個節點的陣列，每個節點是另一個分割或一個窗格split: 分隔線的位置，以區域的比例表示。預設為 0.5；超出 0.1 到 0.9 範圍的值會被限制在此範圍內
窗格節點
窗格是樹的葉節點。它的 surfaces 陣列列出開啟時包含的分頁，且至少要有一個項目。
Surface
窗格 surfaces 陣列中的每個項目都會開啟一個分頁，可以是終端機或瀏覽器：
type:"terminal"或"browser"name: 取代預設標題顯示的分頁標題focus: 設為 true 後，配置建立完成時鍵盤焦點會落在此分頁上command: 僅限終端機：終端機開啟後立即執行的 shell 文字url: 僅限瀏覽器：要載入的頁面cwd: 此分頁的起始目錄，依下方規則解析env: 包含額外環境變數名稱與值的物件
cwd 值的解析方式
~/path: 在你的個人資料夾內解析- 以 / 開頭的路徑: 照原樣使用
./subdir: 接在工作區目錄之後.或 未設定: 沿用工作區目錄
檔案結構
actions、shortcut 或 ui.surfaceTabBar.buttons 前，請安裝最新 nightly 建置。commands 仍用來定義可重複使用的 shell 命令和 workspace 版面。Nightly 建置會加入 actions 註冊表。動作是 surface 分頁列、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 中，但仍能從 surface 分頁列或快捷鍵呼叫。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" }。圖片路徑相對於設定檔。Emoji scale 可省略，預設為 1。支援 SVG、PDF、PNG、JPEG、GIF、TIFF、BMP、HEIC、HEIF、WebP、AVIF、ICO 和 ICNS。
每個按鈕項目可以是動作 ID 字串，也可以是按鈕物件。當你想讓同一個動作使用不同的 surface 標籤、圖示或 tooltip 時，請使用按鈕物件。解析後的按鈕標題也會作為信任提示標題。
請把任何 approval 或 permission flags 直接放進你真正想執行的命令字串中。預設動作目標是 newTabInCurrentPane，所以常見模式是在目前 pane 中開啟新的終端分頁，並在其中啟動 Codex、Claude Code 或 OpenCode。
自訂動作與 Command Palette
actions 項目是 cmux 執行的可重複使用行為。當同一個行為需要從 Command Palette、表面分頁列、快捷鍵或加號按鈕選單觸發時，請使用動作。將 commands 保留給可重複使用的 shell 命令與工作區配置。如果某個動作不應出現在 Command Palette，請將 palette 設為 false。
動作類型
"command": 在終端機中執行 shell 文字。使用 target 選擇目前終端機或目前面板中的新分頁。"agent": 啟動支援的程式碼代理。現在支援 codex 與 claude，並可使用選用引數。"builtin": 為內建 cmux 動作建立別名，例如 cmux.newTerminal、cmux.newBrowser、cmux.splitRight 或 cmux.splitDown。 複製類內建動作：cmux.copyWorkingDirectory 複製終端機的工作目錄，cmux.copyProjectRoot 複製其 Git 儲存庫的根目錄（不在儲存庫中時複製工作目錄），cmux.copyScreen 複製目前可見的畫面內容。 在 SSH、雲端或遠端 tmux 工作區中，cmux 無法查找另一台主機上的 Git 儲存庫，因此 cmux.copyProjectRoot 會複製遠端工作目錄。"workspaceCommand": 執行 commands 中具名的工作區定義。用於多面板配置、自訂工作目錄與啟動命令。"workspace": Create a workspace from an inline workspace definition, with optional restart behavior. Offered in the new-workspace plus-button menu automatically."setting": 修改全域 cmux.json 中的一項設定，例如切換 true/false 設定，或在一組值之間循環。請參閱下方的設定動作。"settingPreset": 一次套用 settingPresets 中具名的一組設定。
動作欄位
title: Command Palette 列標題、表面按鈕標籤、選單項目標題，以及信任提示標題，除非項目另行覆寫。subtitle/description: Command Palette 中的次要文字。description 可作為 subtitle 的別名。keywords: Command Palette 的額外搜尋詞。palette: 自訂動作預設為 true。設為 false 可將動作從 Command Palette 隱藏，同時仍可從其他位置呼叫。shortcut: 選用的動作快捷鍵，使用與設定快捷鍵相同的單鍵或兩段式按鍵序列語法。target: 僅用於 command 與 agent 動作。使用 currentTerminal 或 newTabInCurrentPane。confirm: 執行動作前要求確認。newWorkspaceMenu: Set true to offer any action in the new-workspace plus-button menu, or false to hide a workspace action from it.
Command Palette 行為
Command Palette 會讀取解析後的動作登錄。當 palette 不是 false 時，自訂動作 ID 會新增為列。舊的 commands 會自動新增為自訂列，除非已存在相同產生 ID 的動作。內建命令會保留一般的面板標籤，但覆寫像 cmux.newTerminal 這樣的內建 ID 會改變該共用入口背後的行為。
設定動作
設定動作需指定設定的 path，並且只能指定以下其中一項：set（寫入值）、toggle: true（切換 true/false 設定）、cycle（移到清單中的下一個值，到結尾後回到開頭）或 unset: true（從 cmux.json 移除該鍵，改用設定視窗中的值或預設值）。toggle 與 cycle 會從 cmux 目前使用的值開始，包括你在設定視窗中設定的值。settingPreset 動作會套用 settingPresets 中的一個項目，也就是一份部分的 cmux.json，其中的巢狀物件會逐鍵合併。cmux 在儲存前會依 schema 檢查每項變更，保留你的註解與其他鍵，並立即套用變更。設定動作與預設組只能從全域 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 Machines 時顯示雲端選單項目。 New Cloud Workspace 會使用最近選取的 Cloud 工作區所屬機器，接著使用右側邊欄中第一台機器；若沒有可用機器，則開啟 New Cloud Machine。
{
"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 同時啟動，等待該工作區專用的狀態檔，然後在 exec 前進入建立的目錄。
Workspace layouts
A workspace layout is stored as a workspace action, embedding a full workspace definition directly in the action so it needs no separate commands entry. It supports the same workspace fields plus setup, a bootstrap command sent to the first terminal before that terminal's own command:
{
"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"
}
]
}
}
]
}
}
}
}
}Workspace layouts appear in the plus-button right-click menu automatically. Set newWorkspaceMenu to false to hide one, or to true on any other action to add it to the menu.
You can also create these without writing JSON: right-click the plus button and choose Save Workspace as Layout to capture the current workspace's splits, directories, running agents, and browser tabs into ~/.config/cmux/cmux.json. They are stored as entries in the actions block. Customize Workspace Layouts opens that file in your editor.
Default for new workspaces
Use the Default for New Workspace submenu to pick which saved workspace layout plain New Workspace should run, or choose None to return to a blank terminal. The save dialog also has a Use as default for new workspaces checkbox. The setting is ui.newWorkspace.action; a project-local .cmux/cmux.json value wins over ~/.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"
}
]
}