Користувацькі команди
Визначайте користувацькі команди та макети робочих просторів, додавши файл cmux.json до кореня проєкту або ~/.config/cmux/. Команди з'являються в палітрі команд.
Розташування файлів
cmux шукає конфігурацію у двох місцях:
- Для проєкту:
./.cmux/cmux.json- знаходиться в директорії проєкту, має пріоритет - Локальний fallback:
./cmux.json- і далі підтримується для наявних репозиторіїв - Глобально:
~/.config/cmux/cmux.json- застосовується до всіх проєктів, доповнює локально не визначені команди
actions, shortcut або ui.surfaceTabBar.buttons.Відредагуйте cmux.json, потім натисніть Cmd+Shift+, або виконайте cmux reload-config, щоб застосувати зміни.
Схема
commands і далі визначає повторно використовувані shell-команди та розкладки workspace. Nightly-збірки додають реєстр actions. Дії — це публічні ID, спільні для surface tab bar, Command Palette та скорочень рівня дії.
{
"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, але залишити її доступною на surface tab bar або через скорочення. 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, тому звичний шаблон відкриває нову вкладку термінала в поточній панелі й запускає там Codex, Claude Code або OpenCode.
Користувацькі дії та Command Palette
Запис actions описує повторно використовувану дію, яку запускає cmux. Використовуйте дії, коли та сама поведінка має бути доступна з Command Palette, панелі вкладок поверхні, скорочень або меню кнопки плюс. Залишайте commands для повторно використовуваних shell-команд і розкладок робочих просторів. Установіть palette у false, якщо дія не має з’являтися в Command Palette.
Типи дій
"builtin": Псевдонім для вбудованої дії cmux, наприклад cmux.newTerminal, cmux.newBrowser, cmux.splitRight або cmux.splitDown."command": Запускає shell-текст у терміналі. Використовуйте target, щоб вибрати поточний термінал або нову вкладку в поточній панелі."agent": Запускає підтримуваного кодового агента. Наразі підтримуються codex і claude з необов’язковими аргументами."workspaceCommand": Запускає іменоване визначення робочого простору з commands. Використовуйте для багатопанельних розкладок, власних робочих каталогів і стартових команд.
Поля дії
title: Заголовок рядка Command Palette, підпис кнопки, заголовок пункту меню та заголовок запиту довіри, якщо запис не перевизначає його.subtitle/description: Вторинний текст у Command Palette. description приймається як псевдонім subtitle.keywords: Додаткові пошукові слова для Command Palette.palette: Типово true для користувацьких дій. Установіть false, щоб приховати дію з Command Palette, але залишити її доступною в інших місцях.shortcut: Необов’язкове скорочення дії з тією самою одноразовою або двоетапною chord-синтаксою, що й скорочення налаштувань.target: Лише для дій command і agent. Використовуйте currentTerminal або newTabInCurrentPane.confirm: Запитувати підтвердження перед запуском дії.
Поведінка Command Palette
Command Palette читає розв’язаний реєстр дій. ID користувацьких дій додаються як рядки, коли palette не дорівнює false. Старі commands автоматично додаються як користувацькі рядки, якщо дія з тим самим згенерованим ID ще не існує. Вбудовані команди зберігають звичні назви в палітрі, але перевизначення вбудованого ID, як-от cmux.newTerminal, змінює поведінку за цією спільною точкою входу.
Користувацькі дії кнопки плюс
Використовуйте ui.newWorkspace.action, щоб перевизначити дію кнопки плюс. Використовуйте ui.newWorkspace.contextMenu (або alias rightClick), щоб визначити впорядковане меню правого кліку. Пункти меню можуть бути ID дій, об’єктами дій або { "type": "separator" }.
{
"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 запускаються одночасно, чекають файл стану для цього робочого простору, а потім переходять у створений каталог перед exec.
Прості команди
Проста команда виконує shell-команду в поточному активному терміналі:
{
"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 && для будь-якої конкретної директорії.
Команди робочого простору
Команда робочого простору створює новий робочий простір з користувацьким макетом розділень, терміналів та панелей браузера:
{
"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": Створити новий workspace (за замовчуванням)"ignore": Перемкнутися на наявний workspace"recreate": Закрити та створити заново без запитання"confirm": Запитати користувача перед повторним створенням
Дерево макету
Дерево макету визначає розташування панелей за допомогою рекурсивних вузлів розділення:
Вузол розділення
Ділить простір на два дочірні елементи:
direction:"horizontal"або"vertical"split: Позиція роздільника від 0.1 до 0.9 (за замовчуванням 0.5)children: Рівно два дочірні вузли (розділення або панель)
Вузол панелі
Листовий вузол, що містить одну або більше поверхонь (вкладки всередині панелі).
Визначення поверхні
Кожна поверхня в панелі може бути терміналом або браузером:
type:"terminal"або"browser"name: Користувацький заголовок вкладкиcommand: Shell-команда для автозапуску при створенні (лише термінал)cwd: Робоча директорія для цієї поверхніenv: Змінні середовища як пари ключ-значенняurl: URL для відкриття (лише браузер)focus: Сфокусувати цю поверхню після створення
Визначення робочої директорії
.або не вказано: робоча директорія робочого простору./subdir: відносно робочої директорії робочого простору~/path: розкривається до домашньої директорії- Абсолютний шлях: використовується як є
Повний приклад
{
"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
}
]
}