cmuxcmux/docs

Prilagođene komande

Definirajte prilagođene komande i rasporede radnog prostora dodavanjem datoteke cmux.json u korijenski direktorij vašeg projekta ili ~/.config/cmux/. Komande se pojavljuju u paleti komandi.

Lokacije datoteka

cmux traži konfiguraciju na dva mjesta:

  • Po projektu: ./.cmux/cmux.json - nalazi se u vašem projektnom direktoriju, ima prednost
  • Rezervna lokalna: ./cmux.json - i dalje je podržano za postojeće repozitorije
  • Globalno: ~/.config/cmux/cmux.json - primjenjuje se na sve projekte, dopunjava komande koje nisu definirane lokalno
Lokalne akcije i komande nadjačavaju globalne unose s istim ID-om ili imenom.
Registar akcija je nightly funkcija. Instaliraj najnoviji nightly build prije korištenja actions, shortcut ili ui.surfaceTabBar.buttons.
Akcije lokalne za projekat odmah se pojavljuju u surface tab baru i Command Palette. Prvo pokretanje i dalje traži povjerenje. Povjerenje se veže za tačan fingerprint akcije, a ne za repo. Ikone slika lokalne za projekat ostaju zaključane dok se toj akciji ne ukaže povjerenje.
Ako projektna ili globalna konfiguracija ima grešku u shemi, cmux se vraća na sljedeću važeću konfiguraciju i prikazuje red cmux.json Schema Error u Command Palette. Izaberi ga da otvoriš konfiguracijsku datoteku.

Uredite cmux.json, zatim pritisnite Cmd+Shift+, ili pokrenite cmux reload-config da primijenite promjene.

Shema

commands i dalje definiraju višekratne shell komande i rasporede workspacea. Nightly buildovi dodaju registar actions. Akcije su javni ID-jevi koje dijele surface tab bar, Command Palette i prečice na nivou akcije.

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 registar akcija

actions mapira stabilne ID-jeve na ponašanje koje se može pokrenuti. Koristi ugrađene ID-jeve cmux.newTerminal, cmux.newBrowser, cmux.splitRight i cmux.splitDown da zamijeniš zadane vrijednosti. Koristi vlastite ID-jeve za projektne alate.

palette je zadano true. Postavi na false da sakriješ akciju iz Command Palette, ali je ostaviš dostupnom surface tab baru ili prečici. shortcut koristi istu sintaksu kao prečice u postavkama, na primjer cmd+shift+c ili ["cmd+k", "cmd+c"].

ui.surfaceTabBar.buttons zamjenjuje zadanu listu dugmadi kada je prisutan. Izostavi ugrađeni ID da ga sakriješ. Ikone uvijek koriste oblik objekta: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 } ili { "type": "image", "path": "./icons/codex.svg" }. Putanje slika su relativne prema konfiguracijskoj datoteci. Emoji scale je opcionalan i zadano je 1. Podržani su SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO i ICNS.

Svaki unos dugmeta može biti string ID-ja akcije ili objekat dugmeta. Koristi objekat dugmeta kada želiš istu akciju s drugačijom oznakom na površini, ikonom ili tooltipom. Razriješeni naslov dugmeta koristi se i kao naslov upita za povjerenje.

Stavi sve approval ili permission flagove direktno u string komande koju zaista želiš pokrenuti. Zadani cilj akcije je newTabInCurrentPane, pa je čest obrazac otvoriti novi terminalski tab u trenutnom panelu i tamo pokrenuti Codex, Claude Code ili OpenCode.

Prilagođene akcije i Command Palette

Unos actions je ponovo upotrebljiva stvar koju cmux izvršava. Koristite akcije kada isto ponašanje treba biti dostupno iz Command Palette, površinske trake tabova, prečica ili menija plus dugmeta. Zadržite commands za ponovo upotrebljive shell komande i rasporede radnih prostora. Postavite palette na false kada akcija ne treba biti u Command Palette.

Tipovi akcija

  • "builtin": Alias za ugrađenu cmux akciju kao što su cmux.newTerminal, cmux.newBrowser, cmux.splitRight ili cmux.splitDown.
  • "command": Pokreće shell tekst u terminalu. Koristite target da izaberete trenutni terminal ili novi tab u trenutnom panelu.
  • "agent": Pokreće podržanog programerskog agenta. Trenutno podržava codex i claude, uz opcionalne argumente.
  • "workspaceCommand": Pokreće imenovanu definiciju radnog prostora iz commands. Koristite za rasporede s više panela, prilagođene radne direktorije i početne komande.

Polja akcije

  • title: Naslov reda u Command Palette, oznaka dugmeta, naslov stavke menija i naslov upita za povjerenje, osim ako ga unos ne nadjača.
  • subtitle / description: Sekundarni tekst u Command Palette. description se prihvata kao alias za subtitle.
  • keywords: Dodatni pojmovi za pretragu u Command Palette.
  • palette: Podrazumijevano je true za prilagođene akcije. Postavite false da sakrijete akciju iz Command Palette, a da ostane dostupna drugdje.
  • shortcut: Opcionalna prečica akcije, sa istom sintaksom jednog pritiska ili dvostepenog niza kao prečice u postavkama.
  • target: Samo za command i agent akcije. Koristite currentTerminal ili newTabInCurrentPane.
  • confirm: Zatraži potvrdu prije pokretanja akcije.

Ponašanje Command Palette

Command Palette čita razriješeni registar akcija. ID-jevi prilagođenih akcija dodaju se kao redovi kada palette nije false. Stare commands automatski se dodaju kao prilagođeni redovi, osim ako akcija s istim generisanim ID-om već postoji. Ugrađene komande zadržavaju normalne oznake, ali nadjačavanje ugrađenog ID-a kao što je cmux.newTerminal mijenja ponašanje iza zajedničke ulazne tačke.

Prilagođene akcije plus dugmeta

Koristi ui.newWorkspace.action da zamijeniš ono što plus dugme radi. Koristi ui.newWorkspace.contextMenu (ili alias rightClick) da definiraš uređeni meni desnog klika. Stavke menija mogu biti ID-jevi akcija, objekti akcija ili { "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"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Ovaj primjer čini da običan klik na plus pokrene akciju worktree-agents. Komanda radnog prostora iz commands koristi vidljiv terminal za pripremu da prvo napravi Git worktree. Codex i Claude se pokreću istovremeno, čekaju datoteku stanja specifičnu za radni prostor, zatim prelaze u kreirani direktorij prije exec.

Jednostavne komande

Jednostavna komanda pokreće shell komandu u trenutno fokusiranom terminalu:

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

Polja

  • name: Prikazuje se u paleti komandi (obavezno)
  • description: Neobavezan opis
  • keywords: Dodatni pojmovi za pretraživanje u paleti komandi
  • command: Shell komanda za pokretanje u fokusiranom terminalu
  • confirm: Prikaži dijalog za potvrdu prije pokretanja

Jednostavne komande se pokreću u trenutnom radnom direktoriju fokusiranog terminala. Ako vaša komanda zavisi od putanja relativnih projektu, dodajte prefiks cd "$(git rev-parse --show-toplevel)" && za pokretanje iz korijena repozitorija, ili cd /your/path && za bilo koji specifični direktorij.

Komande radnog prostora

Komanda radnog prostora kreira novi radni prostor s prilagođenim rasporedom podjela, terminala i panela preglednika:

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

Polja radnog prostora

  • name: Naziv kartice radnog prostora (zadano je naziv komande)
  • cwd: Radni direktorij za radni prostor
  • color: Boja kartice radnog prostora
  • layout: Stablo rasporeda koje definira podjele i panele

Ponašanje pri ponovnom pokretanju

Kontrolira što se dešava kada radni prostor istog naziva već postoji:

  • "new": Kreiraj novi radni prostor (zadano)
  • "ignore": Prebaci na postojeći radni prostor
  • "recreate": Zatvori i ponovo kreiraj bez pitanja
  • "confirm": Pitaj korisnika prije ponovnog kreiranja

Stablo rasporeda

Stablo rasporeda definira kako su paneli raspoređeni koristeći rekurzivne čvorove podjele:

Čvor podjele

Dijeli prostor na dva djeteta:

  • direction: "horizontal" ili "vertical"
  • split: Pozicija razdjeljnika od 0.1 do 0.9 (zadano 0.5)
  • children: Točno dva dječja čvora (podjela ili panel)

Čvor panela

Listni čvor koji sadrži jednu ili više površina (kartice unutar panela).

Definicija površine

Svaka površina u panelu može biti terminal ili preglednik:

  • type: "terminal" ili "browser"
  • name: Prilagođeni naslov kartice
  • command: Shell komanda za automatsko pokretanje pri kreiranju (samo terminal)
  • cwd: Radni direktorij za ovu površinu
  • env: Varijable okruženja kao parovi ključ-vrijednost
  • url: URL za otvaranje (samo preglednik)
  • focus: Fokusiraj ovu površinu nakon kreiranja

Razrješavanje radnog direktorija

  • . ili izostavljeno: radni direktorij radnog prostora
  • ./subdir: relativno u odnosu na radni direktorij radnog prostora
  • ~/path: prošireno na kućni direktorij
  • Apsolutna putanja: koristi se kao takvo

Potpuni primjer

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