Comandos personalizados

Defina comandos personalizados e layouts de workspace adicionando um arquivo cmux.json à raiz do seu projeto ou ~/.config/cmux/. Os comandos aparecem na paleta de comandos.

Localizações dos arquivos

O cmux procura configuração em dois lugares:

Por projeto: ./cmux.json — fica no diretório do seu projeto, tem precedência
Global: ~/.config/cmux/cmux.json — aplica-se a todos os projetos, preenche comandos não definidos localmente

Comandos locais substituem comandos globais com o mesmo nome.

As alterações são capturadas automaticamente — nenhum reinício necessário.

Esquema

Um arquivo cmux.json contém um array commands. Cada comando é um comando shell simples ou uma definição completa de workspace:

cmux.json

{
  "commands": [
    {
      "name": "Start Dev",
      "keywords": ["dev", "start"],
      "workspace": { ... }
    },
    {
      "name": "Run Tests",
      "command": "npm test",
      "confirm": true
    }
  ]
}

Comandos simples

Um comando simples executa um comando shell no terminal atualmente focado:

cmux.json

{
  "commands": [
    {
      "name": "Run Tests",
      "keywords": ["test", "check"],
      "command": "npm test",
      "confirm": true
    }
  ]
}

Campos

name — Exibido na paleta de comandos (obrigatório)
description — Descrição opcional
keywords — Termos de pesquisa extras para a paleta de comandos
command — Comando shell para executar no terminal focado
confirm — Mostrar um diálogo de confirmação antes de executar

Comandos simples são executados no diretório de trabalho atual do terminal focado. Se seu comando depende de caminhos relativos ao projeto, prefixe com cd "$(git rev-parse --show-toplevel)" && para executar a partir da raiz do repositório, ou cd /your/path && para qualquer diretório específico.

Comandos de workspace

Um comando de workspace cria um novo workspace com um layout personalizado de divisões, terminais e painéis do navegador:

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" }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Campos de workspace

name — Nome da aba do workspace (padrão é o nome do comando)
cwd — Diretório de trabalho do workspace
color — Cor da aba do workspace
layout — Árvore de layout definindo divisões e painéis

Comportamento de reinício

Controla o que acontece quando um workspace com o mesmo nome já existe:

"ignore" — Mudar para o workspace existente (padrão)
"recreate" — Fechar e recriar sem perguntar
"confirm" — Perguntar ao usuário antes de recriar

Árvore de layout

A árvore de layout define como os painéis são organizados usando nós de divisão recursivos:

Nó de divisão

Divide o espaço em dois filhos:

direction — "horizontal" ou "vertical"
split — Posição do divisor de 0.1 a 0.9 (padrão 0.5)
children — Exatamente dois nós filhos (divisão ou painel)

Nó de painel

Um nó folha contendo uma ou mais superfícies (abas dentro do painel).

Definição de superfície

Cada superfície em um painel pode ser um terminal ou um navegador:

type — "terminal" ou "browser"
name — Título de aba personalizado
command — Comando shell para executar automaticamente na criação (apenas terminal)
cwd — Diretório de trabalho para esta superfície
env — Variáveis de ambiente como pares chave-valor
url — URL para abrir (apenas navegador)
focus — Focar nesta superfície após a criação

Resolução do diretório de trabalho

. ou omitido — diretório de trabalho do workspace
./subdir — relativo ao diretório de trabalho do workspace
~/path — expandido para o diretório home
Caminho absoluto — usado como está

Exemplo completo

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
    }
  ]
}