Özel Komutlar

Proje köküne veya ~/.config/cmux/ dizinine bir cmux.json dosyası ekleyerek özel komutlar ve workspace düzenleri tanımlayın. Komutlar komut paletinde görünür.

Dosya konumları

cmux yapılandırmayı iki yerde arar:

Proje başına: ./.cmux/cmux.json - proje dizininde bulunur, önceliğe sahiptir
Yerel fallback: ./cmux.json - mevcut repolar için hâlâ desteklenir
Genel yapılandırma: ~/.config/cmux/cmux.json - tüm projeler için geçerlidir, yerel olarak tanımlanmayan komutları tamamlar

Yerel eylemler ve komutlar, aynı ID veya ada sahip genel girdilerin yerine geçer.

Eylem kayıt defteri bir nightly özelliğidir. actions, shortcut veya ui.surfaceTabBar.buttons kullanmadan önce en yeni nightly derlemeyi yükleyin.

Projeye yerel eylemler surface sekme çubuğunda ve Command Palette içinde hemen görünür. İlk çalıştırma yine güven ister. Güven repo başına değil, tam eylem parmak izi başına verilir. Projeye yerel görüntü ikonları, o eyleme güvenilene kadar kilitli kalır.

Bir proje veya global config içinde şema hatası varsa cmux bir sonraki geçerli config’e döner ve Command Palette içinde cmux.json Schema Error satırını gösterir. Config dosyasını açmak için seçin.

cmux.json dosyasını düzenleyin, ardından Cmd+Shift+, tuşlarına basın veya değişiklikleri uygulamak için cmux reload-config çalıştırın.

Şema

commands yeniden kullanılabilir shell komutlarını ve çalışma alanı düzenlerini tanımlamaya devam eder. Nightly derlemeler bir actions kayıt defteri ekler. Eylemler surface sekme çubuğu, Command Palette ve eylem düzeyi kısayollar tarafından paylaşılan genel ID’lerdir.

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 eylem kayıt defteri

actions kararlı ID’leri çalıştırılabilir davranışa eşler. Varsayılanları geçersiz kılmak için yerleşik ID’ler olan cmux.newTerminal, cmux.newBrowser, cmux.splitRight ve cmux.splitDown kullanın. Projeye özel araçlar için kendi ID’lerinizi kullanın.

palette varsayılan olarak true değerindedir. Bir eylemi Command Palette içinden gizleyip surface sekme çubuğu veya kısayol üzerinden kullanılabilir tutmak için false yapın. shortcut, ayar kısayollarıyla aynı söz dizimini kullanır. Örneğin cmd+shift+c veya ["cmd+k", "cmd+c"].

ui.surfaceTabBar.buttons mevcut olduğunda varsayılan düğme listesinin yerini alır. Gizlemek için yerleşik bir ID’yi listeden çıkarın. İkonlar her zaman nesne biçimini kullanır: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 } veya { "type": "image", "path": "./icons/codex.svg" }. Görüntü yolları config dosyasına görelidir. Emoji scale isteğe bağlıdır ve varsayılanı 1 değeridir. SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO ve ICNS desteklenir.

Her düğme girdisi bir eylem ID string’i veya düğme nesnesi olabilir. Aynı eylemi farklı bir surface etiketi, ikon veya tooltip ile kullanmak istediğinizde düğme nesnesi kullanın. Çözümlenen düğme başlığı güven isteminin başlığı olarak da kullanılır.

Onay veya izin flag’lerini doğrudan çalıştırmak istediğiniz komut string’inin içine koyun. Varsayılan eylem hedefi newTabInCurrentPane olduğundan yaygın desen, mevcut pane içinde yeni bir terminal sekmesi açıp Codex, Claude Code veya OpenCode’u orada başlatmaktır.

Özel eylemler ve Command Palette

actions girdisi, cmux’un çalıştırdığı yeniden kullanılabilir davranıştır. Aynı davranışın Command Palette, yüzey sekme çubuğu, kısayollar veya artı düğmesi menüsünden kullanılmasını istediğinizde eylemleri kullanın. Yeniden kullanılabilir shell komutları ve çalışma alanı düzenleri için commands kullanmaya devam edin. Bir eylem Command Palette içinde görünmemeliyse palette değerini false yapın.

Eylem türleri

"builtin": cmux.newTerminal, cmux.newBrowser, cmux.splitRight veya cmux.splitDown gibi yerleşik bir cmux eylemi için alias oluşturur.
"command": Terminalde shell metni çalıştırır. Geçerli terminali veya geçerli bölmedeki yeni sekmeyi seçmek için target kullanın.
"agent": Desteklenen bir kodlama ajanı başlatır. Bugün codex ve claude desteklenir, isteğe bağlı argümanlarla.
"workspaceCommand": commands içinden adlandırılmış bir çalışma alanı tanımını çalıştırır. Çok bölmeli düzenler, özel çalışma dizinleri ve başlangıç komutları için kullanın.

Eylem alanları

title: Command Palette satır başlığı, yüzey düğmesi etiketi, menü öğesi başlığı ve güven istemi başlığıdır, bir girdi üzerine yazmadığı sürece.
subtitle / description: Command Palette ikincil metni. description, subtitle için alias olarak kabul edilir.
keywords: Command Palette için ek arama terimleri.
palette: Özel eylemler için varsayılan true değeridir. Eylem başka yerlerden çağrılabilir kalsın ama Command Palette içinde görünmesin istiyorsanız false yapın.
shortcut: Ayar kısayollarıyla aynı tek vuruş veya iki adımlı chord sözdizimini kullanan isteğe bağlı eylem kısayolu.
target: Yalnızca command ve agent eylemleri için. currentTerminal veya newTabInCurrentPane kullanın.
confirm: Eylemi çalıştırmadan önce onay iste.

Command Palette davranışı

Command Palette çözümlenmiş eylem kayıt defterini okur. palette false değilse özel eylem ID’leri satır olarak eklenir. Eski commands, aynı oluşturulmuş ID’ye sahip bir eylem zaten yoksa otomatik olarak özel satırlar olarak eklenir. Yerleşik komutlar normal palet etiketlerini korur, ancak cmux.newTerminal gibi yerleşik bir ID’yi geçersiz kılmak bu ortak giriş noktasının arkasındaki davranışı değiştirir.

Artı düğmesi için özel eylemler

Artı düğmesinin ne yaptığını geçersiz kılmak için ui.newWorkspace.action kullanın. Sıralı sağ tık menüsünü tanımlamak için ui.newWorkspace.contextMenu (veya rightClick alias’ı) kullanın. Menü girdileri eylem ID’leri, eylem nesneleri veya { "type": "separator" } olabilir.

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

Bu örnek, normal artı tıklamasının worktree-agents eylemini çalıştırmasını sağlar. commands içindeki çalışma alanı komutu, önce Git worktree oluşturmak için görünür bir kurulum terminali kullanır. Codex ve Claude aynı anda başlar, çalışma alanına özgü durum dosyasını bekler ve sonra exec öncesinde oluşturulan dizine geçer.

Basit komutlar

Basit bir komut, o an odaklanılan terminalde bir shell komutu çalıştırır:

cmux.json

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

Alanlar

name: Komut paletinde gösterilir (zorunlu)
description: İsteğe bağlı açıklama
keywords: Komut paleti için ekstra arama terimleri
command: Odaklanılan terminalde çalıştırılacak shell komutu
confirm: Çalıştırmadan önce onay iletişim kutusu göster

Basit komutlar, odaklanan terminalin mevcut çalışma dizininde çalıştırılır. Komutunuz projeye göreceli yollar gerektiriyorsa, başına cd "$(git rev-parse --show-toplevel)" && ekleyerek repo kökünden çalıştırabilir veya cd /your/path && ile herhangi bir dizini belirtebilirsiniz.

Workspace komutları

Bir workspace komutu, bölünmeler, terminaller ve tarayıcı panellerinin özel düzeniyle yeni bir workspace oluşturur:

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 alanları

name: Workspace sekme adı (varsayılan komut adıdır)
cwd: Workspace için çalışma dizini
color: Workspace sekme rengi
layout: Bölünmeleri ve panelleri tanımlayan düzen ağacı

Yeniden başlatma davranışı

Aynı adda bir workspace zaten mevcut olduğunda ne olacağını kontrol eder:

"new": Yeni bir workspace oluştur (varsayılan)
"ignore": Mevcut workspace’e geç
"recreate": Sormadan kapat ve yeniden oluştur
"confirm": Yeniden oluşturmadan önce kullanıcıya sor

Düzen ağacı

Düzen ağacı, özyinelemeli bölünme düğümleri kullanarak panellerin nasıl düzenlendiğini tanımlar:

Bölünme düğümü

Alanı iki alt öğeye böler:

direction: "horizontal" veya "vertical"
split: 0.1'den 0.9'a bölücü konumu (varsayılan 0.5)
children: Tam olarak iki alt düğüm (bölünme veya panel)

Panel düğümü

Bir veya daha fazla yüzey (panel içindeki sekmeler) içeren yaprak düğüm.

Yüzey tanımı

Bir paneldeki her yüzey terminal veya tarayıcı olabilir:

type: "terminal" veya "browser"
name: Özel sekme başlığı
command: Oluşturulduğunda otomatik çalıştırılacak shell komutu (yalnızca terminal)
cwd: Bu yüzey için çalışma dizini
env: Anahtar-değer çiftleri olarak ortam değişkenleri
url: Açılacak URL (yalnızca tarayıcı)
focus: Oluşturulduktan sonra bu yüzeye odaklan

Çalışma dizini çözümlemesi

. veya atlanmış: workspace çalışma dizini
./subdir: workspace çalışma dizinine göreli
~/path: ana dizine genişletilmiş
Mutlak yol: olduğu gibi kullanılır

Tam örnek

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