Comandi personalizzati

Definisci comandi personalizzati e layout workspace aggiungendo un file cmux.json alla radice del progetto o ~/.config/cmux/. I comandi appaiono nella palette dei comandi.

Posizioni dei file

cmux cerca la configurazione in due posti:

Per progetto: ./cmux.json — si trova nella directory del progetto, ha la precedenza
Globale: ~/.config/cmux/cmux.json — si applica a tutti i progetti, integra i comandi non definiti localmente

I comandi locali sovrascrivono i comandi globali con lo stesso nome.

Le modifiche vengono rilevate automaticamente — nessun riavvio necessario.

Schema

Un file cmux.json contiene un array commands. Ogni comando è un semplice comando shell o una definizione completa di workspace:

cmux.json

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

Comandi semplici

Un comando semplice esegue un comando shell nel terminale attualmente attivo:

cmux.json

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

Campi

name — Visualizzato nella palette dei comandi (obbligatorio)
description — Descrizione opzionale
keywords — Termini di ricerca aggiuntivi per la palette dei comandi
command — Comando shell da eseguire nel terminale attivo
confirm — Mostra una finestra di conferma prima dell'esecuzione

I comandi semplici vengono eseguiti nella directory di lavoro corrente del terminale focalizzato. Se il comando dipende da percorsi relativi al progetto, aggiungi il prefisso cd "$(git rev-parse --show-toplevel)" && per eseguire dalla radice del repository, o cd /your/path && per qualsiasi directory specifica.

Comandi workspace

Un comando workspace crea un nuovo workspace con un layout personalizzato di divisioni, terminali e pannelli browser:

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

Campi workspace

name — Nome della scheda workspace (predefinito: nome del comando)
cwd — Directory di lavoro del workspace
color — Colore della scheda workspace
layout — Albero di layout che definisce divisioni e pannelli

Comportamento al riavvio

Controlla cosa succede quando esiste già un workspace con lo stesso nome:

"ignore" — Passa al workspace esistente (predefinito)
"recreate" — Chiudi e ricrea senza chiedere
"confirm" — Chiedi all'utente prima di ricreare

Albero di layout

L'albero di layout definisce come i pannelli sono disposti usando nodi di divisione ricorsivi:

Nodo di divisione

Divide lo spazio in due figli:

direction — "horizontal" o "vertical"
split — Posizione del divisore da 0.1 a 0.9 (predefinito 0.5)
children — Esattamente due nodi figli (divisione o pannello)

Nodo pannello

Un nodo foglia contenente una o più superfici (schede all'interno del pannello).

Definizione superficie

Ogni superficie in un pannello può essere un terminale o un browser:

type — "terminal" o "browser"
name — Titolo scheda personalizzato
command — Comando shell da eseguire automaticamente alla creazione (solo terminale)
cwd — Directory di lavoro per questa superficie
env — Variabili d'ambiente come coppie chiave-valore
url — URL da aprire (solo browser)
focus — Metti il focus su questa superficie dopo la creazione

Risoluzione della directory di lavoro

. o omesso — directory di lavoro del workspace
./subdir — relativa alla directory di lavoro del workspace
~/path — espansa alla directory home
Percorso assoluto — usato così com'è

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