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/cmux.json - si trova nella directory del progetto, ha la precedenza
Fallback locale: ./cmux.json - ancora supportato per i repository esistenti
Globale: ~/.config/cmux/cmux.json - si applica a tutti i progetti, integra i comandi non definiti localmente

Le azioni e i comandi locali sostituiscono le voci globali con lo stesso ID o nome.

Il registro delle azioni è una funzione nightly. Installa la build nightly più recente prima di usare actions, shortcut o ui.surfaceTabBar.buttons.

Le azioni locali del progetto compaiono subito nella barra delle schede di superficie e in Command Palette. La prima esecuzione richiede ancora l’attendibilità. L’attendibilità vale per l’impronta esatta dell’azione, non per il repo. Le icone immagine locali del progetto restano bloccate finché quell’azione non viene considerata attendibile.

Se una configurazione di progetto o globale contiene un errore di schema, cmux usa la configurazione valida successiva e mostra una riga cmux.json Schema Error in Command Palette. Selezionala per aprire il file di configurazione.

Modifica cmux.json, quindi premi Cmd+Shift+, oppure esegui cmux reload-config per applicare le modifiche.

Schema di configurazione

commands continua a definire comandi shell riutilizzabili e layout di workspace. Le build nightly aggiungono un registro actions. Le azioni sono gli ID pubblici condivisi dalla barra delle schede di superficie, da Command Palette e dalle scorciatoie a livello di azione.

cmux.json

{
  "actions": {
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "subtitle": "Open Codex in a new terminal tab",
      "command": "codex --dangerously-bypass-approvals-and-sandbox",
      "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": { ... }
    }
  ]
}

Registro azioni nightly

actions associa ID stabili a comportamenti eseguibili. Usa gli ID integrati cmux.newTerminal, cmux.newBrowser, cmux.splitRight e cmux.splitDown per sovrascrivere i valori predefiniti. Usa ID personali per gli strumenti specifici del progetto.

palette è true per impostazione predefinita. Impostalo su false per nascondere un’azione da Command Palette mantenendola disponibile nella barra delle schede di superficie o tramite una scorciatoia. shortcut usa la stessa sintassi delle scorciatoie delle impostazioni, ad esempio cmd+shift+c o ["cmd+k", "cmd+c"].

ui.surfaceTabBar.buttons sostituisce l’elenco predefinito dei pulsanti quando è presente. Ometti un ID integrato per nasconderlo. Le icone usano sempre una forma oggetto: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 } oppure { "type": "image", "path": "./icons/codex.svg" }. I percorsi delle immagini sono relativi al file di configurazione. Il scale delle emoji è facoltativo e il valore predefinito è 1. Sono supportati SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO e ICNS.

Ogni voce pulsante può essere una stringa ID di azione o un oggetto pulsante. Usa un oggetto pulsante quando vuoi la stessa azione con un’etichetta di superficie, un’icona o un tooltip diverso. Il titolo risolto del pulsante viene usato anche come titolo della richiesta di attendibilità.

Inserisci eventuali flag di approvazione o permesso direttamente nella stringa del comando che vuoi davvero eseguire. Il target predefinito dell’azione è newTabInCurrentPane, quindi lo schema comune è aprire una nuova scheda terminale nel pannello corrente e avviare lì Codex, Claude Code o OpenCode.

Azioni personalizzate e Command Palette

Una voce actions è l’elemento riutilizzabile che cmux esegue. Usa le azioni quando lo stesso comportamento deve essere disponibile da Command Palette, dalla barra delle schede di superficie, dalle scorciatoie o dal menu del pulsante più. Mantieni commands per comandi shell riutilizzabili e layout degli spazi di lavoro. Imposta palette su false quando un’azione deve restare fuori da Command Palette.

Tipi di azione

"builtin": Crea un alias per un’azione cmux integrata come cmux.newTerminal, cmux.newBrowser, cmux.splitRight o cmux.splitDown.
"command": Esegue testo shell in un terminale. Usa target per scegliere il terminale corrente o una nuova scheda nel pannello corrente.
"agent": Avvia un agente di programmazione supportato. Oggi supporta codex e claude, con argomenti opzionali.
"workspaceCommand": Esegue una definizione di spazio di lavoro con nome da commands. Usalo per layout multipannello, directory di lavoro personalizzate e comandi di avvio.

Campi dell’azione

title: Titolo della riga in Command Palette, etichetta del pulsante, titolo della voce di menu e titolo della richiesta di attendibilità, salvo override di una voce.
subtitle / description: Testo secondario in Command Palette. description è accettato come alias di subtitle.
keywords: Termini di ricerca aggiuntivi per Command Palette.
palette: Il valore predefinito è true per le azioni personalizzate. Imposta false per nascondere l’azione da Command Palette mantenendola richiamabile altrove.
shortcut: Scorciatoia opzionale dell’azione, con la stessa sintassi a tasto singolo o accordo in due passaggi delle scorciatoie delle impostazioni.
target: Solo per azioni command e agent. Usa currentTerminal o newTabInCurrentPane.
confirm: Chiede conferma prima di eseguire l’azione.

Comportamento di Command Palette

Command Palette legge il registro delle azioni risolto. Gli ID delle azioni personalizzate vengono aggiunti come righe quando palette non è false. I vecchi commands vengono aggiunti automaticamente come righe personalizzate, a meno che esista già un’azione con lo stesso ID generato. I comandi integrati mantengono le etichette normali, ma sostituire un ID integrato come cmux.newTerminal cambia il comportamento dietro quel punto di ingresso condiviso.

Azioni personalizzate del pulsante più

Usa ui.newWorkspace.action per sovrascrivere ciò che fa il pulsante più. Usa ui.newWorkspace.contextMenu (o l’alias rightClick) per definire il menu ordinato del clic destro. Le voci di menu possono essere ID di azione, oggetti azione o { "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 --dangerously-bypass-approvals-and-sandbox"
                      }
                    ]
                  }
                },
                {
                  "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"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Questo esempio fa sì che il normale clic sul più esegua l’azione worktree-agents. Il comando dello spazio di lavoro da commands usa un terminale di configurazione visibile per creare prima il worktree Git. Codex e Claude partono contemporaneamente, attendono il file di stato specifico dello spazio di lavoro, quindi entrano nella directory creata prima di exec.

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"],
      "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:

"new": Crea un nuovo workspace (predefinito)
"ignore": Passa al workspace esistente
"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

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