Brugerdefinerede kommandoer

Definer brugerdefinerede kommandoer og workspace-layouts ved at tilføje en cmux.json-fil til din projektrod eller ~/.config/cmux/. Kommandoer vises i kommandopaletten.

Filplaceringer

cmux leder efter konfiguration to steder:

Per projekt: ./.cmux/cmux.json - befinder sig i din projektmappe, har forrang
Lokal fallback: ./cmux.json - understøttes stadig for eksisterende repos
Global konfiguration: ~/.config/cmux/cmux.json - gælder for alle projekter, udfylder kommandoer, der ikke er defineret lokalt

Lokale handlinger og kommandoer tilsidesætter globale poster med samme id eller navn.

Handlingsregistret er en nightly-funktion. Installer den nyeste nightly-build, før du bruger actions, shortcut eller ui.surfaceTabBar.buttons.

Projektlokale handlinger vises straks i surface-fanelinjen og Command Palette. Første kørsel beder stadig om tillid. Tillid gælder for det præcise handlingsfingeraftryk, ikke for repoet. Projektlokale billedikoner forbliver låst, indtil den handling er godkendt.

Hvis en projektkonfiguration eller global konfiguration har en schemafejl, falder cmux tilbage til den næste gyldige konfiguration og viser rækken cmux.json Schema Error i Command Palette. Vælg den for at åbne konfigurationsfilen.

Rediger cmux.json, og tryk derefter Cmd+Shift+, eller kør cmux reload-config for at anvende ændringer.

Skema

commands definerer stadig genbrugelige shellkommandoer og workspace-layouts. Nightly-builds tilføjer et actions-register. Handlinger er de offentlige ID’er, som deles af surface-fanelinjen, Command Palette og handlingsgenveje.

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": { ... }
    }
  ]
}

Nightly-handlingsregister

actions knytter stabile ID’er til kørbar adfærd. Brug de indbyggede ID’er cmux.newTerminal, cmux.newBrowser, cmux.splitRight og cmux.splitDown til at tilsidesætte standarderne. Brug dine egne ID’er til projektspecifikke værktøjer.

palette er som standard true. Sæt den til false for at skjule en handling fra Command Palette, mens den stadig er tilgængelig for surface-fanelinjen eller en genvej. shortcut bruger samme syntaks som indstillingsgenveje, for eksempel cmd+shift+c eller ["cmd+k", "cmd+c"].

ui.surfaceTabBar.buttons erstatter standardknaplisten, når den findes. Udelad et indbygget ID for at skjule det. Ikoner bruger altid objektformen: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 } eller { "type": "image", "path": "./icons/codex.svg" }. Billedstier er relative til konfigurationsfilen. Emoji scale er valgfri og er som standard 1. SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO og ICNS understøttes.

Hver knapindgang kan enten være en handlings-ID-streng eller et knapobjekt. Brug et knapobjekt, når du vil bruge den samme handling med en anden surface-label, et andet ikon eller tooltip. Den løste knaptitel bruges også som titel i tillidsprompten.

Sæt approval- eller permission-flags direkte i den kommandostreng, du faktisk vil køre. Standardmålet for handlinger er newTabInCurrentPane, så det almindelige mønster er at åbne en ny terminalfane i den aktuelle rude og starte Codex, Claude Code eller OpenCode dér.

Brugerdefinerede handlinger og Command Palette

En actions-post er den genbrugelige ting, som cmux kører. Brug handlinger, når den samme adfærd skal være tilgængelig fra Command Palette, overfladens fanelinje, genveje eller plusknappens menu. Behold commands til genbrugelige shell-kommandoer og arbejdsområdelayouts. Sæt palette til false, når en handling ikke skal vises i Command Palette.

Handlingstyper

"builtin": Opret et alias til en indbygget cmux-handling som cmux.newTerminal, cmux.newBrowser, cmux.splitRight eller cmux.splitDown.
"command": Kør shelltekst i en terminal. Brug target til at vælge den aktuelle terminal eller en ny fane i den aktuelle rude.
"agent": Start en understøttet kodeagent. I dag understøttes codex og claude med valgfrie argumenter.
"workspaceCommand": Kør en navngiven arbejdsområdedefinition fra commands. Brug dette til layouts med flere ruder, brugerdefinerede arbejdsmapper og startkommandoer.

Handlingsfelter

title: Titel i Command Palette, etiket på overfladeknap, menupunkttitel og titel i tillidsdialogen, medmindre en post tilsidesætter den.
subtitle / description: Sekundær tekst i Command Palette. description accepteres som alias for subtitle.
keywords: Ekstra søgeord til Command Palette.
palette: Standard er true for brugerdefinerede handlinger. Sæt false for at skjule handlingen fra Command Palette, mens den stadig kan kaldes andre steder.
shortcut: Valgfri handlingsgenvej med samme syntaks for enkelttryk eller tostegsakkorder som indstillingsgenveje.
target: Kun for command- og agent-handlinger. Brug currentTerminal eller newTabInCurrentPane.
confirm: Spørg før handlingen køres.

Command Palette-adfærd

Command Palette læser det opløste handlingsregister. Brugerdefinerede handlings-id’er tilføjes som rækker, når palette ikke er false. Ældre commands tilføjes automatisk som brugerdefinerede rækker, medmindre en handling med samme genererede id allerede findes. Indbyggede kommandoer beholder deres normale paletnavne, men tilsidesættelse af et indbygget id som cmux.newTerminal ændrer adfærden bag det fælles indgangspunkt.

Tilpassede handlinger for plusknappen

Brug ui.newWorkspace.action til at tilsidesætte, hvad plusknappen gør. Brug ui.newWorkspace.contextMenu (eller aliaset rightClick) til at definere den ordnede højreklikmenu. Menupunkter kan være handlings-ID’er, handlingsobjekter eller { "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"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Dette eksempel får et almindeligt plusklik til at køre handlingen worktree-agents. Arbejdsområdekommandoen fra commands bruger en synlig opsætningsterminal til først at oprette Git-worktree. Codex og Claude starter samtidig, venter på den arbejdsområdespecifikke tilstandsfil og skifter derefter til den oprettede mappe før exec.

Simple kommandoer

En simpel kommando kører en shell-kommando i den aktuelt fokuserede terminal:

cmux.json

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

Felter

name: Vises i kommandopaletten (påkrævet)
description: Valgfri beskrivelse
keywords: Ekstra søgetermer til kommandopaletten
command: Shell-kommando der skal køres i den fokuserede terminal
confirm: Vis en bekræftelsesdialog før kørsel

Simple kommandoer køres i den fokuserede terminals aktuelle arbejdsmappe. Hvis din kommando afhænger af projektrelative stier, sæt foran med cd "$(git rev-parse --show-toplevel)" && for at køre fra repo-roden, eller cd /your/path && for enhver specifik mappe.

Workspace-kommandoer

En workspace-kommando opretter et nyt workspace med et brugerdefineret layout af opdelte terminaler og browserpaneler:

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

Workspace-felter

name: Workspace-fanenavn (standard er kommandoens navn)
cwd: Arbejdsmappe for workspacet
color: Farve på workspace-fanen
layout: Layouttræ der definerer opdelinger og paneler

Genstartsadfærd

Styrer hvad der sker, når der allerede eksisterer et workspace med samme navn:

"new": Opret et nyt workspace (standard)
"ignore": Skift til det eksisterende workspace
"recreate": Luk og genskab uden at spørge
"confirm": Spørg brugeren inden genskabelse

Layouttræ

Layouttræet definerer, hvordan paneler arrangeres ved hjælp af rekursive opdelingsknuder:

Opdelingsknude

Deler plads i to børn:

direction: "horizontal" eller "vertical"
split: Delergitterposition fra 0.1 til 0.9 (standard 0.5)
children: Præcis to underknuder (opdeling eller panel)

Panelknude

En bladknude der indeholder én eller flere overflader (faner inden i panelet).

Overfladedefinition

Hver overflade i et panel kan være en terminal eller en browser:

type: "terminal" eller "browser"
name: Brugerdefineret fanetitel
command: Shell-kommando der automatisk køres ved oprettelse (kun terminal)
cwd: Arbejdsmappe for denne overflade
env: Miljøvariabler som nøgle-værdi-par
url: URL der skal åbnes (kun browser)
focus: Fokuser på denne overflade efter oprettelse

Opløsning af arbejdsmappe

. eller udeladt: workspace-arbejdsmappe
./subdir: relativ til workspace-arbejdsmappe
~/path: udvidet til hjemmemappen
Absolut sti: bruges som den er

Fuldt eksempel

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