Back to Details

cmux-customization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux Customization

cmux 定制

Use this skill for user-facing cmux customization. Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.
本技能用于面向用户的cmux定制。需保留用户现有配置，优先使用基于schema的编辑方式，并在完成后进行验证。

Choose the Right Surface

选择合适的配置层面

  • cmux app preferences: use 
    cmux-settings
    for 
    ~/.config/cmux/cmux.json
    settings such as appearance, sidebar, notifications, browser behavior, automation, and shortcuts.
  • Custom actions, workspace layouts, toolbar buttons, plus-button behavior, and Command Palette entries: edit 
    ~/.config/cmux/cmux.json
    globally or 
    .cmux/cmux.json
    in the project.
  • Terminal rendering and terminal keybindings: use Ghostty config, usually 
    ~/.config/ghostty/config
    . This includes fonts, cursor style, copy-on-select, shell integration, themes, and terminal keybindings.
  • Project-specific behavior: prefer 
    .cmux/cmux.json
    in the project so the customization travels with the repo.
If a request can be handled by Ghostty config, say that and use Ghostty config instead of inventing cmux UI settings.
  • cmux应用偏好设置：使用
    cmux-settings
    配置
    ~/.config/cmux/cmux.json
    中的设置，例如外观、侧边栏、通知、浏览器行为、自动化和快捷键。
  • 自定义操作、工作区布局、工具栏按钮、加号按钮行为以及命令面板条目：全局编辑
    ~/.config/cmux/cmux.json
    或项目中的
    .cmux/cmux.json
    。
  • 终端渲染与终端快捷键：使用Ghostty配置，通常为
    ~/.config/ghostty/config
    。包括字体、光标样式、选中即复制、Shell集成、主题和终端快捷键。
  • 项目特定行为：优先使用项目中的
    .cmux/cmux.json
    ，以便定制设置随代码库同步。
如果请求可通过Ghostty配置实现，请告知用户并使用Ghostty配置，而非自行创建cmux UI设置。

Workflow

工作流程

  1. Inspect existing config before editing.
    bash
    test -f ~/.config/cmux/cmux.json && sed -n '1,220p' ~/.config/cmux/cmux.json
test -f .cmux/cmux.json && sed -n '1,220p' .cmux/cmux.json
  2. Pick global or project-local scope. Ask only when the choice changes behavior meaningfully. Default to project-local for repo-specific commands and global for app preferences.
  3. For app settings and cmux-owned shortcuts, use the settings helper from the installed skill or checkout:
    bash
    ~/.agents/skills/cmux-settings/scripts/cmux-settings list-supported
~/.agents/skills/cmux-settings/scripts/cmux-settings set browser.openTerminalLinksInCmuxBrowser true
~/.agents/skills/cmux-settings/scripts/cmux-settings validate
    If the user installed with 
    skills.sh
    , use 
    ~/.codex/skills/cmux-settings/scripts/cmux-settings
    instead.
  4. For actions and workspace layouts, edit JSONC carefully. Preserve unrelated sections such as 
    vault
    , 
    rightSidebar
    , 
    commands
    , 
    actions
    , 
    ui
    , and 
    notifications
    .
  5. Reload config after successful edits:
    bash
    cmux reload-config
  6. Verify the configured entrypoint exists. For shortcuts, read back the binding. For custom actions, confirm the action ID and where it should appear.
  1. 编辑前检查现有配置。
    bash
    test -f ~/.config/cmux/cmux.json && sed -n '1,220p' ~/.config/cmux/cmux.json
test -f .cmux/cmux.json && sed -n '1,220p' .cmux/cmux.json
  2. 选择全局或项目本地作用域。仅当选择会显著改变行为时询问用户。针对仓库特定命令默认使用项目本地作用域，针对应用偏好设置默认使用全局作用域。
  3. 针对应用设置和cmux专属快捷键，使用已安装技能或检出版本中的设置助手：
    bash
    ~/.agents/skills/cmux-settings/scripts/cmux-settings list-supported
~/.agents/skills/cmux-settings/scripts/cmux-settings set browser.openTerminalLinksInCmuxBrowser true
~/.agents/skills/cmux-settings/scripts/cmux-settings validate
    如果用户通过
    skills.sh
    安装，请改用
    ~/.codex/skills/cmux-settings/scripts/cmux-settings
    。
  4. 针对操作和工作区布局，谨慎编辑JSONC。保留无关部分，例如
    vault
    、
    rightSidebar
    、
    commands
    、
    actions
    、
    ui
    和
    notifications
    。
  5. 编辑成功后重新加载配置：
    bash
    cmux reload-config
  6. 验证配置的入口点是否存在。对于快捷键，读取绑定信息；对于自定义操作，确认操作ID及其应显示的位置。

Common Patterns

常见模式

Add a Command Palette action that opens Codex in a new tab:
json
{
  "actions": {
    "codex-new-tab": {
      "type": "agent",
      "agent": "codex",
      "title": "Codex",
      "subtitle": "Start Codex in this workspace",
      "target": "newTabInCurrentPane",
      "palette": true
    }
  }
}
Add a project workspace layout:
json
{
  "commands": [
    {
      "name": "dev",
      "type": "workspace",
      "cwd": ".",
      "layout": {
        "type": "split",
        "direction": "horizontal",
        "children": [
          { "type": "pane", "surfaces": [{ "type": "terminal", "command": "bun dev" }] },
          { "type": "pane", "surfaces": [{ "type": "browser", "url": "http://localhost:3000" }] }
        ]
      }
    }
  ]
}
Add surface toolbar buttons:
json
{
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        {
          "action": "codex-new-tab",
          "title": "Codex",
          "icon": { "type": "symbol", "name": "terminal" }
        }
      ]
    }
  }
}
添加一个在新标签页打开Codex的命令面板操作：
json
{
  "actions": {
    "codex-new-tab": {
      "type": "agent",
      "agent": "codex",
      "title": "Codex",
      "subtitle": "Start Codex in this workspace",
      "target": "newTabInCurrentPane",
      "palette": true
    }
  }
}
添加项目工作区布局：
json
{
  "commands": [
    {
      "name": "dev",
      "type": "workspace",
      "cwd": ".",
      "layout": {
        "type": "split",
        "direction": "horizontal",
        "children": [
          { "type": "pane", "surfaces": [{ "type": "terminal", "command": "bun dev" }] },
          { "type": "pane", "surfaces": [{ "type": "browser", "url": "http://localhost:3000" }] }
        ]
      }
    }
  ]
}
添加界面工具栏按钮：
json
{
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        {
          "action": "codex-new-tab",
          "title": "Codex",
          "icon": { "type": "symbol", "name": "terminal" }
        }
      ]
    }
  }
}

Validation

验证

  • App settings: run 
    cmux-settings validate
    .
  • JSONC shape: keep valid JSONC and avoid duplicate keys.
  • Runtime reload: run 
    cmux reload-config
    when the CLI is available.
  • User-facing action: confirm the action title, shortcut, or toolbar placement the user asked for.
  • 应用设置：运行
    cmux-settings validate
    。
  • JSONC格式：保持有效的JSONC，避免重复键。
  • 运行时重新加载：当CLI可用时，运行
    cmux reload-config
    。
  • 用户可见操作：确认用户要求的操作标题、快捷键或工具栏位置。

Rules

规则

  • Do not overwrite whole top-level config sections unless you own the full section.
  • Do not store secrets directly in actions, commands, or prompts. Use environment variables or the user's secret manager.
  • Do not use app/runtime sleeps or timing workarounds in generated commands.
  • Do not add a cmux setting for behavior Ghostty already owns.
  • Keep labels short enough for menus, buttons, and the Command Palette.
  • 除非你负责整个顶级配置部分，否则不要覆盖整个部分。
  • 不要在操作、命令或提示中直接存储密钥。使用环境变量或用户的密钥管理器。
  • 不要在生成的命令中使用应用/运行时休眠或定时变通方法。
  • 不要为Ghostty已支持的行为添加cmux设置。
  • 标签要足够简短，以适配菜单、按钮和命令面板。