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

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

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

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 — Рівно два дочірні вузли (розділення або панель)

Вузол панелі

Листовий вузол, що містить одну або більше поверхонь (вкладки всередині панелі).

Визначення поверхні

Кожна поверхня в панелі може бути терміналом або браузером:

type — "terminal" або "browser"
name — Користувацький заголовок вкладки
command — Shell-команда для автозапуску при створенні (лише термінал)
cwd — Робоча директорія для цієї поверхні
env — Змінні середовища як пари ключ-значення
url — URL для відкриття (лише браузер)
focus — Сфокусувати цю поверхню після створення

Визначення робочої директорії

. або не вказано — робоча директорія робочого простору
./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
    }
  ]
}