Brugerdefinerede kommandoer og handlinger

I cmux.json lærer du cmux dine egne rutiner: shellkommandoer, du ofte kører, arbejdsområder, der åbner med en forudindstillet opstilling af terminaler og browsere, og handlinger, du kan knytte til genveje, knapper i fanelinjen og kommandopaletten. Læg en fil i .cmux/cmux.json i et projekt, i ~/.config/cmux/cmux.json for alle projekter, eller begge steder.

Hvor cmux læser cmux.json

Poster kan komme fra en projektfil, en brugerfil eller begge. For projektfiler starter cmux i den aktuelle mappe og tjekker også hver overordnet mappe ovenover.

• Projekt: ./.cmux/cmux.json (findes ved at søge opad fra arbejdsmappen; har forrang for brugerfilen)
• Lokal fallback: ./cmux.json (understøttes stadig for eksisterende repos)
• Brugerniveau: ~/.config/cmux/cmux.json (delt af alle projekter; leverer det, som en projektfil ikke definerer)

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

Shellkommandoer

Den mindste post er et navn plus en command-streng. Når du vælger den i kommandopaletten, skrives strengen i den terminal, der har fokus, og køres.

{
  "commands": [
    {
      "name": "Format Changed Files",
      "description": "Run the formatter on files that differ from main",
      "keywords": [
        "fmt",
        "prettier",
        "style"
      ],
      "command": "git diff --name-only main -- '*.ts' '*.tsx' | xargs npx prettier --write"
    },
    {
      "name": "Reset Local Database",
      "keywords": [
        "db",
        "wipe"
      ],
      "command": "cd \"$(git rev-parse --show-toplevel)\" && ./scripts/db-reset.sh",
      "confirm": true
    }
  ]
}

Felter for shellkommandoer

• name: Påkrævet, ikke-tom etiket, som du vælger i kommandopaletten
• command: Den shelltekst, som cmux skriver i den aktive terminal og kører
• description: Valgfri sekundær tekst, der vises ved siden af posten
• keywords: Ekstra ord, der skal matche denne post, når du søger i kommandopaletten
• confirm: Sæt til true for at få en bekræftelsesprompt, hver gang før den kører

En shellkommando kører der, hvor den aktive terminal tilfældigvis befinder sig. Når kommandoen skal have et forudsigeligt udgangspunkt, så start den med cd "$(git rev-parse --show-toplevel)" && for at gå til toppen af Git-repositoriet, eller med cd /some/folder && for at låse den til en fast mappe.

Kommandoer, der åbner et arbejdsområde

Giv en kommando et workspace-objekt i stedet for en command-streng, så åbner den i stedet et nyt arbejdsområde, opbygget som et træ af opdelte paneler med terminaler og browsere. En post skal have præcis ét af de to.

{
  "commands": [
    {
      "name": "API Stack",
      "keywords": [
        "api",
        "server",
        "logs"
      ],
      "restart": "confirm",
      "workspace": {
        "name": "API",
        "cwd": "./services/api",
        "color": "#10b981",
        "env": {
          "PORT": "8080"
        },
        "layout": {
          "direction": "vertical",
          "split": 0.65,
          "children": [
            {
              "direction": "horizontal",
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Server",
                        "command": "go run ./cmd/api",
                        "focus": true
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Worker",
                        "command": "go run ./cmd/worker",
                        "env": {
                          "QUEUE": "default"
                        }
                      }
                    ]
                  }
                }
              ]
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Logs",
                    "cwd": "/var/log",
                    "command": "tail -F system.log"
                  },
                  {
                    "type": "browser",
                    "name": "Health",
                    "url": "http://localhost:8080/healthz"
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Felter i et workspace-objekt

• name: Titel på arbejdsområdet; bruger kommandoens navn, hvis den mangler
• cwd: Basismappe for arbejdsområdet; hver fanes cwd fortolkes ud fra den
• layout: Rodknuden i layouttræet, som er beskrevet nedenfor
• color: Farve i sidebjælken, som #RRGGBB-hex eller navnet på en arbejdsområdefarve
• env: Environment variables inherited by every shell in the workspace
• setup: Bootstrap command sent to the workspace's first terminal before that terminal's own command

Når arbejdsområdet allerede er åbent

Angiv restart på kommandoen for at bestemme, hvad der sker, hvis et arbejdsområde med samme navn allerede findes:

• "new": Opret et nyt workspace (standard)
• "confirm": Spørg først, og erstat det derefter, hvis du accepterer
• "recreate": Erstat det med det samme uden at spørge
• "ignore": Skift til det eksisterende workspace

Sådan beskriver du et layout

Et layout er et træ. Hver indre knude deler sit område i to, og hvert blad er et panel med faner.

Opdelingsknuder

En opdeling deler sit område i to dele:

• direction: "horizontal" eller "vertical"
• children: Et array med præcis to knuder, som hver især er en anden opdeling eller et panel
• split: Hvor skillelinjen sidder, som en brøkdel af området. Standard er 0.5; værdier uden for 0.1 til 0.9 begrænses

Panelknuder

Et panel er et blad i træet. Dets surfaces-array angiver de faner, det åbner med, og skal indeholde mindst én post.

Flader

Hver post i et panels surfaces-array åbner én fane, som enten er en terminal eller en browser:

• type: "terminal" eller "browser"
• name: Fanetitel, der vises i stedet for standardtitlen
• focus: Sæt til true for at give denne fane tastaturfokus, når layoutet er bygget
• command: Kun terminaler: shelltekst, der køres, så snart terminalen åbner
• url: Kun browsere: den side, der skal indlæses
• cwd: Startmappe for denne fane, fortolket efter reglerne nedenfor
• env: Et objekt med ekstra navne og værdier for miljøvariabler

Sådan fortolkes cwd-værdier

• ~/path: slås op i din hjemmemappe
• En sti, der begynder med /: bruges som den er
• ./subdir: føjes til arbejdsområdets mappe
• . eller ikke angivet: arver arbejdsområdets mappe

Filstruktur

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.

{
  "actions": {
    "cmux.newTerminal": {
      "type": "agent",
      "agent": "claude",
      "title": "Claude Code",
      "subtitle": "Start Claude Code in a new tab"
    },
    "lint": {
      "type": "command",
      "title": "Lint",
      "subtitle": "Run the linter in a fresh tab",
      "keywords": [
        "eslint",
        "check"
      ],
      "command": "npm run lint",
      "shortcut": [
        "cmd+k",
        "cmd+l"
      ],
      "icon": {
        "type": "symbol",
        "name": "checkmark.seal"
      }
    },
    "scratch-dir": {
      "type": "command",
      "title": "Scratch Directory",
      "command": "cd \"$(mktemp -d)\"",
      "target": "currentTerminal",
      "palette": false,
      "icon": {
        "type": "emoji",
        "value": "📝",
        "scale": 0.85
      }
    },
    "api-stack": {
      "type": "workspaceCommand",
      "title": "API Stack",
      "commandName": "API Stack"
    }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.splitRight",
        "lint",
        {
          "action": "scratch-dir",
          "tooltip": "cd into a new temp folder"
        }
      ]
    }
  },
  "commands": [
    {
      "name": "API Stack",
      "keywords": [
        "api"
      ],
      "workspace": {
        "cwd": "./services/api",
        "layout": {
          "pane": {
            "surfaces": [
              {
                "type": "terminal",
                "name": "Server",
                "command": "go run ./cmd/api"
              }
            ]
          }
        }
      }
    }
  ]
}

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

• "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.
• "builtin": Opret et alias til en indbygget cmux-handling som cmux.newTerminal, cmux.newBrowser, cmux.splitRight eller cmux.splitDown. Indbyggede kopihandlinger: cmux.copyWorkingDirectory kopierer terminalens arbejdsmappe, cmux.copyProjectRoot kopierer roden af dens git-repository (eller arbejdsmappen uden for et) og cmux.copyScreen kopierer den synlige skærm. I et SSH-, cloud- eller fjern-tmux-arbejdsområde kopierer cmux.copyProjectRoot fjernarbejdsmappen, fordi cmux ikke kan slå git-repositoriet op på den anden vært.
• "workspaceCommand": Kør en navngiven arbejdsområdedefinition fra commands. Brug dette til layouts med flere ruder, brugerdefinerede arbejdsmapper og startkommandoer.
• "workspace": Create a workspace from an inline workspace definition, with optional restart behavior. Offered in the new-workspace plus-button menu automatically.
• "setting": Ændr én indstilling i din globale cmux.json, for eksempel slå en true/false-indstilling til eller fra eller skift gennem en liste af værdier. Se Indstillingshandlinger nedenfor.
• "settingPreset": Anvend en navngiven gruppe indstillinger fra settingPresets i ét trin.

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.
• newWorkspaceMenu: Set true to offer any action in the new-workspace plus-button menu, or false to hide a workspace action from it.

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.

Indstillingshandlinger

En indstillingshandling angiver en path til en indstilling og præcis én af set (skriv en værdi), toggle: true (slå en true/false-indstilling om), cycle (gå til næste værdi i en liste og start forfra efter den sidste) eller unset: true (fjern nøglen fra cmux.json, så værdien fra Indstillinger-vinduet eller standardværdien gælder). toggle og cycle tager udgangspunkt i den værdi, cmux bruger, også en du har sat i Indstillinger-vinduet. En settingPreset-handling anvender en post fra settingPresets, en delvis cmux.json, hvis indlejrede objekter flettes nøgle for nøgle. cmux kontrollerer hver ændring mod skemaet, før den gemmes, bevarer dine kommentarer og andre nøgler og anvender ændringen med det samme. Indstillingshandlinger og presets kører kun fra din globale cmux.json og de pakker, den henviser til; projektkonfigurationer kan ikke erklære dem.

{
  "actions": {
    "scroll.cycle": {
      "type": "setting",
      "title": "Cycle Scroll Speed",
      "path": "terminal.scrollSpeed",
      "cycle": [1.0, 1.4, 1.8]
    },
    "editor.wrap": {
      "type": "setting",
      "title": "Toggle Editor Word Wrap",
      "path": "fileEditor.wordWrap",
      "toggle": true
    },
    "sidebar.quiet": {
      "type": "settingPreset",
      "title": "Quiet Sidebar",
      "preset": "sidebar.quiet"
    }
  },
  "settingPresets": {
    "sidebar.quiet": {
      "sidebar": { "showPorts": false, "showPullRequests": false, "showLog": false }
    }
  }
}

De samme ændringer kan laves fra en terminal: cmux config set terminal.scrollSpeed 1.4, cmux config toggle fileEditor.wordWrap og cmux config preset sidebar.quiet.

Med confirm: true spørger cmux, før der gemmes, og viser den tilsvarende cmux config-kommando. Stier deles ved hvert ".", så en nøgle, der selv indeholder "." (f.eks. en workspaceGroups.byCwd-post for ~/src/app.web), kan ikke ændres på denne måde. Rediger den direkte i cmux.json.

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" }. Når den ikke er angivet, viser menuen cmux.newWorkspace (⌘N), cmux.newCloudWorkspace (⌘Y), cmux.newCloudMachine (⇧⌘Y), cmux.newTerminal (⌘T), cmux.newBrowser (⇧⌘L) med deres aktuelle genveje. Cloud-punkter vises kun, når Cloud Machines er aktiveret. New Cloud Workspace bruger maskinen fra det senest valgte Cloud-arbejdsområde og derefter den første maskine i højre sidepanel; hvis ingen brugbar maskine findes, åbnes New Cloud Machine.

{
  "actions": {
    "worktree-agents": {
      "type": "workspaceCommand",
      "title": "Agents in New Worktree",
      "commandName": "Agents in New Worktree",
      "icon": {
        "type": "symbol",
        "name": "arrow.triangle.branch"
      }
    }
  },
  "ui": {
    "newWorkspace": {
      "action": "worktree-agents",
      "contextMenu": [
        "worktree-agents",
        {
          "type": "separator"
        },
        {
          "action": "cmux.newWorkspace",
          "title": "Blank Workspace"
        },
        {
          "action": "cmux.newBrowser",
          "title": "Browser"
        }
      ]
    }
  },
  "commands": [
    {
      "name": "Agents in New Worktree",
      "description": "Branch off a new Git worktree, then run Codex and Claude Code in it side by side",
      "workspace": {
        "name": "Worktree",
        "layout": {
          "direction": "vertical",
          "split": 0.7,
          "children": [
            {
              "direction": "horizontal",
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Codex",
                        "command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; echo \"Waiting for the worktree...\"; until [ -s \"$marker\" ]; do sleep 0.25; done; cd \"$(cat \"$marker\")\" && exec codex --yolo"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Claude",
                        "command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; echo \"Waiting for the worktree...\"; until [ -s \"$marker\" ]; do sleep 0.25; done; cd \"$(cat \"$marker\")\" && exec claude --dangerously-skip-permissions"
                      }
                    ]
                  }
                }
              ]
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Setup",
                    "command": "marker=\"${TMPDIR:-/tmp}/cmux-wt-${CMUX_WORKSPACE_ID:-local}\"; rm -f \"$marker\"; root=$(git rev-parse --show-toplevel) || exit 1; branch=\"wt-$(date +%m%d-%H%M%S)\"; wt=\"$root/../$(basename \"$root\")-$branch\"; git -C \"$root\" worktree add -b \"$branch\" \"$wt\" && printf \"%s\\n\" \"$wt\" > \"$marker\" && cd \"$wt\" && exec \"${SHELL:-/bin/zsh}\" -l",
                    "focus": true
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

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.

Workspace layouts

A workspace layout is stored as a workspace action, embedding a full workspace definition directly in the action so it needs no separate commands entry. It supports the same workspace fields plus setup, a bootstrap command sent to the first terminal before that terminal's own command:

{
  "actions": {
    "pair-review": {
      "type": "workspace",
      "title": "Pair Review",
      "icon": {
        "type": "symbol",
        "name": "person.2.wave.2"
      },
      "restart": "ignore",
      "newWorkspaceMenu": true,
      "workspace": {
        "name": "Review",
        "cwd": "~/src/app",
        "setup": "git pull --ff-only",
        "layout": {
          "direction": "horizontal",
          "split": 0.55,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Diff",
                    "command": "git log -p -n 5",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Codex",
                    "command": "codex"
                  },
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Workspace layouts appear in the plus-button right-click menu automatically. Set newWorkspaceMenu to false to hide one, or to true on any other action to add it to the menu.

You can also create these without writing JSON: right-click the plus button and choose Save Workspace as Layout to capture the current workspace's splits, directories, running agents, and browser tabs into ~/.config/cmux/cmux.json. They are stored as entries in the actions block. Customize Workspace Layouts opens that file in your editor.

Default for new workspaces

Use the Default for New Workspace submenu to pick which saved workspace layout plain New Workspace should run, or choose None to return to a blank terminal. The save dialog also has a Use as default for new workspaces checkbox. The setting is ui.newWorkspace.action; a project-local .cmux/cmux.json value wins over ~/.config/cmux/cmux.json.

Fuldt eksempel

{
  "actions": {
    "cmux.newTerminal": {
      "type": "command",
      "title": "Codex",
      "command": "codex --yolo",
      "shortcut": "cmd+t",
      "icon": {
        "type": "image",
        "path": "./icons/codex.svg"
      }
    },
    "review": {
      "type": "agent",
      "agent": "claude",
      "args": "--permission-mode plan",
      "title": "Plan with Claude",
      "shortcut": "cmd+shift+p",
      "icon": {
        "type": "symbol",
        "name": "list.bullet.clipboard"
      }
    },
    "storybook": {
      "type": "workspaceCommand",
      "commandName": "Storybook",
      "newWorkspaceMenu": true
    },
    "typecheck": {
      "type": "command",
      "title": "Typecheck",
      "command": "npx tsc --noEmit",
      "target": "newTabInCurrentPane",
      "confirm": false,
      "icon": {
        "type": "emoji",
        "value": "🔎"
      }
    }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "review",
        {
          "action": "typecheck",
          "title": "tsc"
        },
        "cmux.newBrowser",
        "cmux.splitDown"
      ]
    },
    "newWorkspace": {
      "contextMenu": [
        "storybook",
        {
          "type": "separator"
        },
        "cmux.newTerminal",
        "cmux.newBrowser"
      ]
    }
  },
  "commands": [
    {
      "name": "Storybook",
      "description": "Component explorer with a live preview beside it",
      "keywords": [
        "ui",
        "components",
        "stories"
      ],
      "workspace": {
        "name": "Storybook",
        "cwd": "./packages/ui",
        "color": "#a855f7",
        "layout": {
          "direction": "horizontal",
          "split": 0.4,
          "children": [
            {
              "direction": "vertical",
              "split": 0.5,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Storybook",
                        "command": "npx storybook dev -p 6006 --no-open",
                        "focus": true
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Tests",
                        "command": "npx vitest --watch",
                        "env": {
                          "CI": "false"
                        }
                      }
                    ]
                  }
                }
              ]
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "browser",
                    "name": "Preview",
                    "url": "http://localhost:6006"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Install Dependencies",
      "keywords": [
        "install",
        "deps"
      ],
      "command": "npm ci",
      "confirm": true
    },
    {
      "name": "Open Changelog",
      "keywords": [
        "changes",
        "release"
      ],
      "command": "${EDITOR:-vi} CHANGELOG.md"
    }
  ]
}