cmuxcmux
/docs

#Ö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 --yolo",
      "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.
  • "workspace": Create a workspace from an inline workspace definition, with optional restart behavior. Offered in the new-workspace plus-button menu automatically.

#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.
  • 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 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 --yolo"
                      }
                    ]
                  }
                },
                {
                  "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.

#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:

cmux.json
{
  "actions": {
    "review-setup": {
      "type": "workspace",
      "title": "Review Setup",
      "icon": { "type": "symbol", "name": "rectangle.stack.badge.plus" },
      "restart": "confirm",
      "workspace": {
        "name": "Review",
        "cwd": "~/code/app",
        "setup": "git fetch --all --prune",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "Claude", "command": "claude", "focus": true }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  { "type": "terminal", "name": "OpenCode", "command": "opencode" }
                ]
              }
            }
          ]
        }
      }
    }
  }
}

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.

#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
  • 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
  • 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 --yolo",
      "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
    }
  ]
}