cmuxcmux
/docs

#ពាក្យបញ្ជាផ្ទាល់ខ្លួន

កំណត់ពាក្យបញ្ជាផ្ទាល់ខ្លួននិងប្លង់ workspace ដោយបន្ថែមឯកសារ cmux.json ទៅឫសគម្រោងរបស់អ្នក ឬ ~/.config/cmux/។ ពាក្យបញ្ជាលេចឡើងក្នុងបន្ទះពាក្យបញ្ជា។

#ទីតាំងឯកសារ

cmux រកការកំណត់រចនាសម្ព័ន្ធនៅ២កន្លែង:

  • តាមគម្រោង: ./.cmux/cmux.json - ស្ថិតក្នុងថតគម្រោងរបស់អ្នក, មានអាទិភាព
  • Local fallback: ./cmux.json - នៅតែគាំទ្រសម្រាប់ repos ដែលមានស្រាប់
  • សកល: ~/.config/cmux/cmux.json - អនុវត្តចំពោះគម្រោងទាំងអស់, បំពេញពាក្យបញ្ជាដែលមិនបានកំណត់ក្នុងតំបន់
Actions និង commands ក្នុង local នឹង override entries global ដែលមាន ID ឬ name ដូចគ្នា។
បញ្ជីចុះឈ្មោះ action គឺជាមុខងារ nightly។ ដំឡើង nightly build ថ្មីបំផុត មុនពេលប្រើ actions, shortcut, ឬ ui.surfaceTabBar.buttons។
Actions ដែលនៅក្នុង project នឹងបង្ហាញភ្លាមៗនៅក្នុង surface tab bar និង Command Palette។ ការរត់លើកដំបូងនៅតែសួរឱ្យទុកចិត្ត។ ការទុកចិត្តគឺតាម fingerprint action ដែលត្រូវគ្នាពិតប្រាកដ មិនមែនតាម repo ទេ។ រូបតំណាង image ក្នុង project នឹងនៅតែ lock រហូតដល់ action នោះត្រូវបានទុកចិត្ត។
បើ config របស់ project ឬ global មាន schema error, cmux នឹងត្រឡប់ទៅ config ដែលត្រឹមត្រូវបន្ទាប់ ហើយបង្ហាញ row cmux.json Schema Error នៅក្នុង Command Palette។ ជ្រើសវា ដើម្បីបើកឯកសារ config។

កែ cmux.json បន្ទាប់មកចុច Cmd+Shift+, ឬរត់ cmux reload-config ដើម្បីអនុវត្តការផ្លាស់ប្តូរ។

#គ្រោងការណ៍

commands នៅតែកំណត់ shell commands និង workspace layouts ដែលអាចប្រើឡើងវិញបាន។ Nightly builds បន្ថែមបញ្ជីចុះឈ្មោះ actions។ Actions គឺជា public IDs ដែល surface tab bar, Command Palette និង shortcuts កម្រិត action ប្រើរួមគ្នា។

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": { ... }
    }
  ]
}

#បញ្ជីចុះឈ្មោះ action សម្រាប់ nightly

actions ភ្ជាប់ stable IDs ទៅនឹង behavior ដែលអាចរត់បាន។ ប្រើ built-in IDs cmux.newTerminal, cmux.newBrowser, cmux.splitRight, និង cmux.splitDown ដើម្បី override defaults។ ប្រើ IDs ផ្ទាល់ខ្លួនសម្រាប់ tools របស់ project។

palette មានតម្លៃ default ជា true។ កំណត់ជា false ដើម្បីលាក់ action ពី Command Palette ប៉ុន្តែនៅតែអាចហៅបានពី surface tab bar ឬ shortcut។ shortcut ប្រើ syntax ដូច settings shortcuts ដែរ ឧទាហរណ៍ cmd+shift+c ឬ ["cmd+k", "cmd+c"]។

ui.surfaceTabBar.buttons នឹងជំនួសបញ្ជី buttons default នៅពេលមាន។ ដក built-in ID ចេញ ដើម្បីលាក់វា។ Icons តែងតែប្រើ object shape: { "type": "symbol", "name": "play.circle" }, { "type": "emoji", "value": "🧪", "scale": 0.9 }, ឬ { "type": "image", "path": "./icons/codex.svg" }។ Image paths គឺ relative ទៅឯកសារ config។ Emoji scale គឺ optional ហើយ default ជា 1។ គាំទ្រ SVG, PDF, PNG, JPEG, GIF, TIFF, BMP, HEIC, HEIF, WebP, AVIF, ICO, និង ICNS។

ធាតុ button នីមួយៗអាចជា action ID string ឬ button object។ ប្រើ button object នៅពេលអ្នកចង់បាន action ដូចគ្នា ប៉ុន្តែមាន surface label, icon, ឬ tooltip ផ្សេង។ ចំណងជើង button ដែល resolve រួចក៏ត្រូវបានប្រើជាចំណងជើង trust prompt ផងដែរ។

ដាក់ approval ឬ permission flags ណាមួយដោយផ្ទាល់ក្នុង command string ដែលអ្នកចង់រត់ពិតប្រាកដ។ Action target default គឺ newTabInCurrentPane ដូច្នេះ pattern ទូទៅគឺបើក terminal tab ថ្មីក្នុង pane បច្ចុប្បន្ន ហើយចាប់ផ្តើម Codex, Claude Code, ឬ OpenCode នៅទីនោះ។

#Custom actions និង Command Palette

actions គឺជាធាតុដែល cmux រត់ឡើងវិញបាន។ ប្រើ actions នៅពេល behavior ដូចគ្នាត្រូវមានពី Command Palette, surface tab bar, shortcuts ឬ menu របស់ plus button។ ទុក commands សម្រាប់ shell commands និង workspace layouts ដែលប្រើឡើងវិញ។ ដាក់ palette ជា false នៅពេល action មិនគួរបង្ហាញក្នុង Command Palette។

#ប្រភេទ action

  • "builtin": Alias ទៅ built-in cmux action ដូចជា cmux.newTerminal, cmux.newBrowser, cmux.splitRight ឬ cmux.splitDown។
  • "command": រត់ shell text ក្នុង terminal។ ប្រើ target ដើម្បីជ្រើស terminal បច្ចុប្បន្ន ឬ tab ថ្មីក្នុង pane បច្ចុប្បន្ន។
  • "agent": ចាប់ផ្តើម coding agent ដែលគាំទ្រ។ បច្ចុប្បន្នគាំទ្រ codex និង claude ជាមួយ args ជម្រើស។
  • "workspaceCommand": រត់ named workspace definition ពី commands។ ប្រើវាសម្រាប់ multi-pane layouts, working directories ផ្ទាល់ខ្លួន និង startup commands។
  • "workspace": Create a workspace from an inline workspace definition, with optional restart behavior. Offered in the new-workspace plus-button menu automatically.

#វាល action

  • title: ចំណងជើង row ក្នុង Command Palette, label របស់ surface button, title របស់ menu item និង title របស់ trust prompt លុះត្រាតែ entry មួយ override វា។
  • subtitle / description: អត្ថបទ secondary ក្នុង Command Palette។ description អាចប្រើជា alias សម្រាប់ subtitle។
  • keywords: ពាក្យស្វែងរកបន្ថែមសម្រាប់ Command Palette។
  • palette: លំនាំដើមគឺ true សម្រាប់ custom actions។ ដាក់ false ដើម្បីលាក់ action ពី Command Palette ខណៈនៅតែអាចហៅពីកន្លែងផ្សេងបាន។
  • shortcut: Shortcut action ជម្រើស ដោយប្រើ syntax single-stroke ឬ two-stroke chord ដូច settings shortcuts។
  • target: សម្រាប់ command និង agent actions ប៉ុណ្ណោះ។ ប្រើ currentTerminal ឬ newTabInCurrentPane។
  • confirm: សួរបញ្ជាក់មុនរត់ action។
  • 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

Command Palette អាន action registry ដែល resolve រួច។ Custom action IDs ត្រូវបន្ថែមជា rows នៅពេល palette មិនមែន false។ commands ចាស់ៗត្រូវបន្ថែមស្វ័យប្រវត្តិជា custom rows លុះត្រាតែមាន action ដែលមាន generated ID ដូចគ្នារួចហើយ។ Built-in commands រក្សា labels ធម្មតា ប៉ុន្តែការជំនួស built-in ID ដូចជា cmux.newTerminal នឹងផ្លាស់ប្តូរ behavior នៅក្រោយ entrypoint រួមនោះ។

#Actions ផ្ទាល់ខ្លួនសម្រាប់ប៊ូតុង plus

ប្រើ ui.newWorkspace.action ដើម្បី override អ្វីដែលប៊ូតុង plus ធ្វើ។ ប្រើ ui.newWorkspace.contextMenu (ឬ alias rightClick) ដើម្បីកំណត់ right-click menu ដែលមានលំដាប់។ Menu entries អាចជា action IDs, action objects, ឬ { "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 --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"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

ឧទាហរណ៍នេះធ្វើឱ្យការចុច plus ធម្មតារត់ action worktree-agents។ Workspace command ពី commands ប្រើ setup terminal ដែលមើលឃើញ ដើម្បីបង្កើត Git worktree ជាមុន។ Codex និង Claude ចាប់ផ្តើមពេលតែមួយ រង់ចាំ state file សម្រាប់ workspace នោះ បន្ទាប់មក cd ទៅ directory ដែលបានបង្កើត មុន 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:

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.

#ពាក្យបញ្ជាសាមញ្ញ

ពាក្យបញ្ជាសាមញ្ញដំណើរការពាក្យបញ្ជា shell ក្នុងទែមីណាល​ដែលបានផ្ដោតបច្ចុប្បន្ន:

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

#វាល

  • name: បង្ហាញក្នុងបន្ទះពាក្យបញ្ជា (ចាំបាច់)
  • description: ការពិពណ៌នាជាជម្រើស
  • keywords: ពាក្យស្វែងរកបន្ថែមសម្រាប់បន្ទះពាក្យបញ្ជា
  • command: ពាក្យបញ្ជា shell ដំណើរការក្នុងទែមីណាល​ដែលបានផ្ដោត
  • confirm: បង្ហាញប្រអប់បញ្ជាក់មុននឹងដំណើរការ

ពាក្យបញ្ជាសាមញ្ញដំណើរការក្នុងថតការងារបច្ចុប្បន្នរបស់ terminal ដែលកំពុងផ្ដោត។ ប្រសិនបើពាក្យបញ្ជារបស់អ្នកពឹងផ្អែកលើផ្លូវទាក់ទងនឹងគម្រោង សូមបន្ថែមពីមុខ cd "$(git rev-parse --show-toplevel)" && ដើម្បីដំណើរការពីឫសនៃ repo ឬ cd /your/path && សម្រាប់ថតណាមួយជាក់លាក់។

#ពាក្យបញ្ជា workspace

ពាក្យបញ្ជា workspace បង្កើត workspace ថ្មីជាមួយប្លង់ផ្ទាល់ខ្លួននៃការបំបែក, ទែមីណាល, និងបន្ទះកម្មវិធីរុករក:

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

  • name: ឈ្មោះផ្ទាំង workspace (លំនាំដើមគឺឈ្មោះពាក្យបញ្ជា)
  • cwd: ថតការងារសម្រាប់ workspace
  • color: ពណ៌ផ្ទាំង workspace
  • 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: ដើមប្លង់ដែលកំណត់ការបំបែកនិងបន្ទះ

#ឥរិយាបថចាប់ផ្ដើមឡើងវិញ

គ្រប់គ្រងអ្វីដែលកើតឡើងនៅពេល workspace ដែលមានឈ្មោះដូចគ្នារួចមានស្រាប់:

  • "new": បង្កើត workspace ថ្មី (លំនាំដើម)
  • "ignore": ប្ដូរទៅ workspace ដែលមានស្រាប់
  • "recreate": បិទហើយបង្កើតឡើងវិញដោយមិនសួរ
  • "confirm": សួរអ្នកប្រើប្រាស់មុននឹងបង្កើតឡើងវិញ

#ដើមប្លង់

ដើមប្លង់កំណត់របៀបដែលបន្ទះត្រូវបានរៀបចំដោយប្រើថ្នាំងការបំបែករៀងគ្នា:

#ថ្នាំងការបំបែក

ចែកចន្លោះទៅជាកូន២:

  • direction: "horizontal" ឬ "vertical"
  • split: ទីតាំងខ្សែបំបែកពី 0.1 ដល់ 0.9 (លំនាំដើម 0.5)
  • children: ថ្នាំងកូនពិតប្រាកដ២ (ការបំបែក ឬបន្ទះ)

#ថ្នាំងបន្ទះ

ថ្នាំងស្លឹកមួយដែលមាន surface មួយ ឬច្រើន (ផ្ទាំងនៅក្នុងបន្ទះ)។

#និយាម surface

surface នីមួយៗក្នុងបន្ទះអាចជាទែមីណាល​ ឬកម្មវិធីរុករក:

  • type: "terminal" ឬ "browser"
  • name: ចំណងជើងផ្ទាំងផ្ទាល់ខ្លួន
  • command: ពាក្យបញ្ជា shell ដំណើរការដោយស្វ័យប្រវត្តិពេលបង្កើត (ទែមីណាល​តែប៉ុណ្ណោះ)
  • cwd: ថតការងារសម្រាប់ surface នេះ
  • env: អថេរបរិស្ថានជាគូ key-value
  • url: URL ដែលត្រូវបើក (កម្មវិធីរុករកតែប៉ុណ្ណោះ)
  • focus: ផ្ដោតលើ surface នេះបន្ទាប់ពីបង្កើត

#ការដោះស្រាយថតការងារ

  • . ឬ លុបចោល: ថតការងារ workspace
  • ./subdir: ទាក់ទងនឹងថតការងារ workspace
  • ~/path: ពង្រីកទៅថតផ្ទះ
  • ផ្លូវដាច់ខាត: ប្រើដូចដែលមាន

#ឧទាហរណ៍ពេញលេញ

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