Comandos personalizados

Define comandos personalizados y diseños de workspace añadiendo un archivo cmux.json a la raíz de tu proyecto o ~/.config/cmux/. Los comandos aparecen en la paleta de comandos.

Ubicaciones de archivos

cmux busca configuración en dos lugares:

Por proyecto: ./cmux.json — se encuentra en tu directorio de proyecto, tiene prioridad
Global: ~/.config/cmux/cmux.json — se aplica a todos los proyectos, completa los comandos no definidos localmente

Los comandos locales anulan los comandos globales con el mismo nombre.

Los cambios se recogen automáticamente — no se necesita reinicio.

Esquema

Un archivo cmux.json contiene un array commands. Cada comando es un comando de shell simple o una definición completa de workspace:

cmux.json

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

Comandos simples

Un comando simple ejecuta un comando de shell en el terminal actualmente enfocado:

cmux.json

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

Campos

name — Se muestra en la paleta de comandos (requerido)
description — Descripción opcional
keywords — Términos de búsqueda adicionales para la paleta de comandos
command — Comando de shell para ejecutar en el terminal enfocado
confirm — Mostrar un diálogo de confirmación antes de ejecutar

Los comandos simples se ejecutan en el directorio de trabajo actual de la terminal enfocada. Si tu comando depende de rutas relativas al proyecto, prefija con cd "$(git rev-parse --show-toplevel)" && para ejecutar desde la raíz del repositorio, o cd /your/path && para cualquier directorio específico.

Comandos de workspace

Un comando de workspace crea un nuevo workspace con un diseño personalizado de divisiones, terminales y paneles de 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 — Nombre de la pestaña del workspace (por defecto es el nombre del comando)
cwd — Directorio de trabajo del workspace
color — Color de la pestaña del workspace
layout — Árbol de diseño que define divisiones y paneles

Comportamiento de reinicio

Controla qué sucede cuando ya existe un workspace con el mismo nombre:

"ignore" — Cambiar al workspace existente (por defecto)
"recreate" — Cerrar y recrear sin preguntar
"confirm" — Preguntar al usuario antes de recrear

Árbol de diseño

El árbol de diseño define cómo se organizan los paneles usando nodos de división recursivos:

Nodo de división

Divide el espacio en dos hijos:

direction — "horizontal" o "vertical"
split — Posición del divisor de 0.1 a 0.9 (por defecto 0.5)
children — Exactamente dos nodos hijos (división o panel)

Nodo de panel

Un nodo hoja que contiene una o más superficies (pestañas dentro del panel).

Definición de superficie

Cada superficie en un panel puede ser un terminal o un navegador:

type — "terminal" o "browser"
name — Título de pestaña personalizado
command — Comando de shell para ejecutar automáticamente al crear (solo terminal)
cwd — Directorio de trabajo para esta superficie
env — Variables de entorno como pares clave-valor
url — URL para abrir (solo navegador)
focus — Enfocar esta superficie después de crearla

Resolución del directorio de trabajo

. o omitido — directorio de trabajo del workspace
./subdir — relativo al directorio de trabajo del workspace
~/path — expandido al directorio home
Ruta absoluta — se usa tal cual

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