Egendefinerte kommandoer

Definer egendefinerte kommandoer og workspace-oppsett ved å legge til en cmux.json-fil i prosjektets rotmappe eller ~/.config/cmux/. Kommandoer vises i kommandopaletten.

Filplasseringer

cmux søker etter konfigurasjon to steder:

Per prosjekt: ./.cmux/cmux.json - ligger i prosjektmappen din, har forrang
Lokal reserve: ./cmux.json - støttes fortsatt for eksisterende repoer
Global konfigurasjon: ~/.config/cmux/cmux.json - gjelder alle prosjekter, fyller inn kommandoer som ikke er definert lokalt

Lokale handlinger og kommandoer overstyrer globale oppføringer med samme ID eller navn.

Handlingsregisteret er en nightly-funksjon. Installer den nyeste nightly-byggingen før du bruker actions, shortcut eller ui.surfaceTabBar.buttons.

Prosjektlokale handlinger vises umiddelbart i surface-fanelinjen og Command Palette. Første kjøring ber fortsatt om tillit. Tillit gjelder det eksakte handlingsfingeravtrykket, ikke repoet. Prosjektlokale bildeikoner forblir låst til handlingen er godkjent.

Hvis en prosjektkonfigurasjon eller global konfigurasjon har en skjemafeil, faller cmux tilbake til neste gyldige konfigurasjon og viser raden cmux.json Schema Error i Command Palette. Velg den for å åpne konfigurasjonsfilen.

Rediger cmux.json, og trykk deretter Cmd+Shift+, eller kjør cmux reload-config for å bruke endringene.

Skjema

commands definerer fortsatt gjenbrukbare shellkommandoer og workspace-oppsett. Nightly-bygg legger til et actions-register. Handlinger er de offentlige ID-ene som deles av surface-fanelinjen, Command Palette og handlingssnarveier.

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 kobler stabile ID-er til kjørbar atferd. Bruk de innebygde ID-ene cmux.newTerminal, cmux.newBrowser, cmux.splitRight og cmux.splitDown for å overstyre standardene. Bruk egne ID-er for prosjektspesifikke verktøy.

palette er som standard true. Sett den til false for å skjule en handling fra Command Palette, samtidig som den fortsatt er tilgjengelig i surface-fanelinjen eller via en snarvei. shortcut bruker samme syntaks som innstillingssnarveier, for eksempel cmd+shift+c eller ["cmd+k", "cmd+c"].

ui.surfaceTabBar.buttons erstatter standardknapplisten når den finnes. Utelat en innebygd ID for å skjule den. Ikoner bruker alltid objektform: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 } eller { "type": "image", "path": "./icons/codex.svg" }. Bildestier er relative til konfigurasjonsfilen. Emoji scale er valgfritt og standard er 1. SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO og ICNS støttes.

Hver knappeoppføring kan enten være en handlings-ID-streng eller et knappeobjekt. Bruk et knappeobjekt når du vil ha samme handling med en annen surface-etikett, ikon eller tooltip. Den løste knappetittelen brukes også som tittel i tillitsforespørselen.

Legg approval- eller permission-flagg direkte i kommandostrengen du faktisk vil kjøre. Standardmålet for handlingen er newTabInCurrentPane, så det vanlige mønsteret er å åpne en ny terminalfane i gjeldende panel og starte Codex, Claude Code eller OpenCode der.

Egendefinerte handlinger og Command Palette

En actions-oppføring er den gjenbrukbare tingen cmux kjører. Bruk handlinger når samme oppførsel skal være tilgjengelig fra Command Palette, overflatefanelinjen, snarveier eller plussknappmenyen. Behold commands for gjenbrukbare shell-kommandoer og arbeidsområdeoppsett. Sett palette til false når en handling ikke skal vises i Command Palette.

Handlingstyper

"builtin": Alias til en innebygd cmux-handling som cmux.newTerminal, cmux.newBrowser, cmux.splitRight eller cmux.splitDown.
"command": Kjører shell-tekst i en terminal. Bruk target for å velge gjeldende terminal eller en ny fane i gjeldende panel.
"agent": Starter en støttet kodeagent. I dag støttes codex og claude, med valgfrie argumenter.
"workspaceCommand": Kjører en navngitt arbeidsområdedefinisjon fra commands. Bruk dette for flerpane-layouter, egendefinerte arbeidsmapper og oppstartskommandoer.

Handlingsfelt

title: Tittel i Command Palette-raden, knappetekst, menypunkttittel og tittel i tillitsdialogen, med mindre en oppføring overstyrer den.
subtitle / description: Sekundærtekst i Command Palette. description godtas som alias for subtitle.
keywords: Ekstra søkeord for Command Palette.
palette: Standard er true for egendefinerte handlinger. Sett false for å skjule handlingen fra Command Palette, men fortsatt kunne kalle den andre steder.
shortcut: Valgfri handlingssnarvei, med samme syntaks for enkelttast eller totrinnsakkord som innstillingssnarveier.
target: Kun for command- og agent-handlinger. Bruk currentTerminal eller newTabInCurrentPane.
confirm: Spør før handlingen kjøres.

Command Palette-oppførsel

Command Palette leser det løste handlingsregisteret. Egendefinerte handlings-ID-er legges til som rader når palette ikke er false. Eldre commands legges automatisk til som egendefinerte rader med mindre en handling med samme genererte ID allerede finnes. Innebygde kommandoer beholder de vanlige palettetikettene, men overstyring av en innebygd ID som cmux.newTerminal endrer oppførselen bak det delte inngangspunktet.

Tilpassede handlinger for plussknappen

Bruk ui.newWorkspace.action for å overstyre hva plussknappen gjør. Bruk ui.newWorkspace.contextMenu (eller aliaset rightClick) for å definere den ordnede høyreklikkmenyen. Menyoppføringer 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 eksempelet gjør at et vanlig plussklikk kjører handlingen worktree-agents. Arbeidsområdekommandoen fra commands bruker en synlig oppsettsterminal til først å opprette Git-worktree. Codex og Claude starter samtidig, venter på den arbeidsområdespesifikke tilstandsfilen og går deretter inn i den opprettede mappen før exec.

Enkle kommandoer

En enkel kommando kjører en shell-kommando i den for øyeblikket fokuserte terminalen:

cmux.json

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

Felter

name: Vises i kommandopaletten (påkrevd)
description: Valgfri beskrivelse
keywords: Ekstra søkeord for kommandopaletten
command: Shell-kommando som kjøres i den fokuserte terminalen
confirm: Vis en bekreftelsesdialog før kjøring

Enkle kommandoer kjøres i den fokuserte terminalens gjeldende arbeidskatalog. Hvis kommandoen din avhenger av prosjektrelative stier, legg til prefiks cd "$(git rev-parse --show-toplevel)" && for å kjøre fra repo-roten, eller cd /your/path && for en hvilken som helst spesifikk katalog.

Workspace-kommandoer

En workspace-kommando oppretter et nytt workspace med et egendefinert oppsett av delinger, terminaler og nettleserpaneler:

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 kommandonavn)
cwd: Arbeidsmappe for workspacet
color: Farge på workspace-fanen
layout: Oppsettstre som definerer delinger og paneler

Omstartsatferd

Styrer hva som skjer når et workspace med samme navn allerede eksisterer:

"new": Opprett et nytt workspace (standard)
"ignore": Bytt til det eksisterende workspacet
"recreate": Lukk og gjenopprett uten å spørre
"confirm": Spør brukeren før gjenoppretting

Oppsettstre

Oppsettstreet definerer hvordan paneler er arrangert ved hjelp av rekursive delingsknuter:

Delingsknute

Deler plassen i to barn:

direction: "horizontal" eller "vertical"
split: Delerposisjon fra 0.1 til 0.9 (standard 0.5)
children: Nøyaktig to barneknuter (deling eller panel)

Panelknute

En bladknute som inneholder én eller flere overflater (faner innen panelet).

Overflatedefinisjon

Hver overflate i et panel kan være en terminal eller en nettleser:

type: "terminal" eller "browser"
name: Egendefinert fanetittel
command: Shell-kommando som kjøres automatisk ved opprettelse (kun terminal)
cwd: Arbeidsmappe for denne overflaten
env: Miljøvariabler som nøkkel-verdi-par
url: URL som skal åpnes (kun nettleser)
focus: Fokuser på denne overflaten etter opprettelse

Oppløsning av arbeidsmappe

. eller utelatt: workspace-arbeidsmappe
./subdir: relativ til workspace-arbeidsmappen
~/path: utvidet til hjemmemappen
Absolutt sti: brukes som den er

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