自訂指令
透過在專案根目錄或 ~/.config/cmux/ 中新增 cmux.json 檔案來定義自訂指令和工作區版面配置。指令將顯示於指令面板中。
檔案位置
cmux 在兩個地方尋找設定：
- 依專案：
./cmux.json— 位於專案目錄中，優先採用 - 全域：
~/.config/cmux/cmux.json— 適用於所有專案，補充本地未定義的指令
本地指令會覆蓋同名的全域指令。
變更會自動生效 — 無需重新啟動。
結構描述
cmux.json 檔案包含一個 commands 陣列。每個指令可以是簡單的 shell 指令或完整的工作區定義：
cmux.json
{
"commands": [
{
"name": "Start Dev",
"keywords": ["dev", "start"],
"workspace": { ... }
},
{
"name": "Run Tests",
"command": "npm test",
"confirm": true
}
]
}簡單指令
簡單指令會在目前聚焦的終端機中執行 shell 指令：
cmux.json
{
"commands": [
{
"name": "Run Tests",
"keywords": ["test", "check"],
"command": "npm test",
"confirm": true
}
]
}欄位
name— 顯示於指令面板（必填）description— 選填說明keywords— 指令面板的額外搜尋詞command— 在聚焦終端機中執行的 shell 指令confirm— 執行前顯示確認對話框
簡單指令在當前聚焦終端的工作目錄中執行。如果指令依賴於專案相對路徑，請在前面加上 cd "$(git rev-parse --show-toplevel)" && 以從倉庫根目錄執行，或使用 cd /your/path && 指定任意目錄。
工作區指令
工作區指令會建立一個新工作區，具有自訂的分割、終端機和瀏覽器窗格版面配置：
cmux.json
{
"commands": [
{
"name": "Dev Environment",
"keywords": ["dev", "fullstack"],
"restart": "confirm",
"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— 定義分割和窗格的版面配置樹
重新啟動行為
控制當同名工作區已存在時的行為：
"ignore"— 切換至現有工作區（預設）"recreate"— 無需詢問直接關閉並重新建立"confirm"— 重新建立前詢問使用者
版面配置樹
版面配置樹使用遞迴分割節點定義窗格的排列方式：
分割節點
將空間分割為兩個子節點：
direction—"horizontal"或"vertical"split— 分割線位置，從 0.1 到 0.9（預設 0.5）children— 恰好兩個子節點（分割或窗格）
窗格節點
包含一個或多個 surface（窗格內索引標籤）的葉節點。
Surface 定義
窗格中的每個 surface 可以是終端機或瀏覽器：
type—"terminal"或"browser"name— 自訂索引標籤標題command— 建立時自動執行的 shell 指令（僅限終端機）cwd— 此 surface 的工作目錄env— 以鍵值對形式表示的環境變數url— 要開啟的 URL（僅限瀏覽器）focus— 建立後聚焦此 surface
工作目錄解析
.或 省略 — 工作區工作目錄./subdir— 相對於工作區工作目錄~/path— 展開至主目錄- 絕對路徑 — 按原樣使用
完整範例
cmux.json
{
"commands": [
{
"name": "Web Dev",
"description": "Docs site with live preview",
"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": "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"],
"restart": "ignore",
"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
}
]
}