Benutzerdefinierte Befehle

Definieren Sie benutzerdefinierte Befehle und Workspace-Layouts, indem Sie eine cmux.json-Datei in Ihr Projektstammverzeichnis oder ~/.config/cmux/ hinzufügen. Befehle erscheinen in der Befehlspalette.

Dateispeicherorte

cmux sucht an zwei Stellen nach Konfiguration:

Projektspezifisch: ./cmux.json — liegt in Ihrem Projektverzeichnis, hat Vorrang
Global: ~/.config/cmux/cmux.json — gilt für alle Projekte, ergänzt lokal nicht definierte Befehle

Lokale Befehle überschreiben globale Befehle mit demselben Namen.

Änderungen werden automatisch übernommen — kein Neustart erforderlich.

Schema

Eine cmux.json-Datei enthält ein commands-Array. Jeder Befehl ist entweder ein einfacher Shell-Befehl oder eine vollständige Workspace-Definition:

cmux.json

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

Einfache Befehle

Ein einfacher Befehl führt einen Shell-Befehl im aktuell fokussierten Terminal aus:

cmux.json

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

Felder

name — Wird in der Befehlspalette angezeigt (erforderlich)
description — Optionale Beschreibung
keywords — Zusätzliche Suchbegriffe für die Befehlspalette
command — Shell-Befehl, der im fokussierten Terminal ausgeführt wird
confirm — Bestätigungsdialog vor der Ausführung anzeigen

Einfache Befehle werden im aktuellen Arbeitsverzeichnis des fokussierten Terminals ausgeführt. Wenn Ihr Befehl projektrelative Pfade benötigt, stellen Sie cd "$(git rev-parse --show-toplevel)" && voran, um vom Repository-Stammverzeichnis auszuführen, oder cd /your/path && für ein beliebiges Verzeichnis.

Workspace-Befehle

Ein Workspace-Befehl erstellt einen neuen Workspace mit einem benutzerdefinierten Layout aus Aufteilungen, Terminals und Browser-Fenstern:

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

Workspace-Felder

name — Name des Workspace-Tabs (Standard ist Befehlsname)
cwd — Arbeitsverzeichnis für den Workspace
color — Farbe des Workspace-Tabs
layout — Layout-Baum, der Aufteilungen und Fenster definiert

Neustart-Verhalten

Steuert, was passiert, wenn bereits ein Workspace mit demselben Namen existiert:

"ignore" — Zum vorhandenen Workspace wechseln (Standard)
"recreate" — Schließen und ohne Rückfrage neu erstellen
"confirm" — Benutzer vor der Neuerstellung fragen

Layout-Baum

Der Layout-Baum definiert, wie Fenster mithilfe rekursiver Aufteilungsknoten angeordnet werden:

Aufteilungsknoten

Teilt den Platz in zwei Kindelemente auf:

direction — "horizontal" oder "vertical"
split — Teilerposition von 0.1 bis 0.9 (Standard 0.5)
children — Genau zwei Kindknoten (Aufteilung oder Fenster)

Fensterknoten

Ein Blattknoten, der eine oder mehrere Oberflächen enthält (Tabs innerhalb des Fensters).

Oberflächendefinition

Jede Oberfläche in einem Fenster kann ein Terminal oder ein Browser sein:

type — "terminal" oder "browser"
name — Benutzerdefinierter Tab-Titel
command — Shell-Befehl, der bei der Erstellung automatisch ausgeführt wird (nur Terminal)
cwd — Arbeitsverzeichnis für diese Oberfläche
env — Umgebungsvariablen als Schlüssel-Wert-Paare
url — URL zum Öffnen (nur Browser)
focus — Diese Oberfläche nach der Erstellung fokussieren

Arbeitsverzeichnis-Auflösung

. oder weggelassen — Workspace-Arbeitsverzeichnis
./subdir — relativ zum Workspace-Arbeitsverzeichnis
~/path — auf Home-Verzeichnis erweitert
Absoluter Pfad — wird unverändert verwendet

Vollständiges Beispiel

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