cmuxcmux
/docs

#Користувацькі команди

Визначайте користувацькі команди та макети робочих просторів, додавши файл cmux.json до кореня проєкту або ~/.config/cmux/. Команди з'являються в палітрі команд.

#Розташування файлів

cmux шукає конфігурацію у двох місцях:

  • Для проєкту: ./.cmux/cmux.json - знаходиться в директорії проєкту, має пріоритет
  • Локальний fallback: ./cmux.json - і далі підтримується для наявних репозиторіїв
  • Глобально: ~/.config/cmux/cmux.json - застосовується до всіх проєктів, доповнює локально не визначені команди
Локальні дії та команди перевизначають глобальні записи з тим самим ID або назвою.
Реєстр дій — це функція nightly. Установіть найновішу nightly-збірку перед використанням actions, shortcut або ui.surfaceTabBar.buttons.
Локальні для проєкту дії одразу з’являються на surface tab bar і в Command Palette. Під час першого запуску все одно з’являється запит довіри. Довіра прив’язана до точного fingerprint дії, а не до репозиторію. Локальні для проєкту іконки-зображення залишаються заблокованими, доки цій дії не буде надано довіру.
Якщо конфігурація проєкту або глобальна конфігурація має помилку схеми, cmux повертається до наступної чинної конфігурації та показує рядок cmux.json Schema Error у Command Palette. Виберіть його, щоб відкрити файл конфігурації.

Відредагуйте cmux.json, потім натисніть Cmd+Shift+, або виконайте cmux reload-config, щоб застосувати зміни.

#Схема

commands і далі визначає повторно використовувані shell-команди та розкладки workspace. Nightly-збірки додають реєстр actions. Дії — це публічні ID, спільні для surface tab bar, Command Palette та скорочень рівня дії.

cmux.json
{
  "actions": {
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "subtitle": "Open Codex in a new terminal tab",
      "command": "codex --yolo",
      "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. Використовуйте для багатопанельних розкладок, власних робочих каталогів і стартових команд.
  • "workspace": Create a workspace from an inline workspace definition, with optional restart behavior. Offered in the new-workspace plus-button menu automatically.

#Поля дії

  • 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: Запитувати підтвердження перед запуском дії.
  • 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 читає розв’язаний реєстр дій. ID користувацьких дій додаються як рядки, коли palette не дорівнює false. Старі commands автоматично додаються як користувацькі рядки, якщо дія з тим самим згенерованим ID ще не існує. Вбудовані команди зберігають звичні назви в палітрі, але перевизначення вбудованого ID, як-от cmux.newTerminal, змінює поведінку за цією спільною точкою входу.

#Користувацькі дії кнопки плюс

Використовуйте ui.newWorkspace.action, щоб перевизначити дію кнопки плюс. Використовуйте ui.newWorkspace.contextMenu (або alias 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 --yolo"
                      }
                    ]
                  }
                },
                {
                  "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.

#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:

cmux.json
{
  "actions": {
    "review-setup": {
      "type": "workspace",
      "title": "Review Setup",
      "icon": { "type": "symbol", "name": "rectangle.stack.badge.plus" },
      "restart": "confirm",
      "workspace": {
        "name": "Review",
        "cwd": "~/code/app",
        "setup": "git fetch --all --prune",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "Claude", "command": "claude", "focus": true }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "OpenCode", "command": "opencode" }
                ]
              }
            }
          ]
        }
      }
    }
  }
}

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.

#Прості команди

Проста команда виконує 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"],
      "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: Колір вкладки робочого простору
  • env: Environment variables inherited by every shell in the workspace
  • setup: Bootstrap command sent to the workspace's first terminal before that terminal's own command
  • 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: розкривається до домашньої директорії
  • Абсолютний шлях: використовується як є

#Повний приклад

cmux.json
{
  "actions": {
    "web-dev": { "type": "workspaceCommand", "commandName": "Web Dev" },
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "command": "codex --yolo",
      "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
    }
  ]
}