{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "title": "cmux.json",
  "description": "cmux configuration. Global cmux.json supports app settings, shortcuts, actions, custom commands, and workspace layouts. Project-local .cmux/cmux.json supports actions, commands, and UI action wiring.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "default": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
      "description": "Optional schema URL for editor completion and validation."
    },
    "schemaVersion": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Schema version for forward-compatible migrations. Newer versions are parsed on a best-effort basis."
    },
    "actions": {
      "title": "actions",
      "description": "Action registry used by the surface tab bar, Command Palette, shortcuts, and plus-button menu.",
      "type": "object",
      "additionalProperties": true
    },
    "ui": {
      "title": "ui",
      "description": "UI action wiring, including surface tab bar buttons and plus-button behavior.",
      "type": "object",
      "additionalProperties": true
    },
    "commands": {
      "title": "commands",
      "description": "Custom shell commands and workspace layout definitions.",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "newWorkspaceCommand": {
      "type": "string",
      "description": "Legacy name of a workspace command to run when creating a new workspace. Prefer ui.newWorkspace.action for new configs."
    },
    "surfaceTabBarButtons": {
      "title": "surfaceTabBarButtons",
      "description": "Legacy root-level surface tab bar buttons. Prefer ui.surfaceTabBar.buttons for new configs.",
      "type": "array",
      "items": {
        "oneOf": [
          { "type": "string" },
          {
            "type": "object",
            "additionalProperties": true
          }
        ]
      }
    },
    "app": {
      "title": "app",
      "description": "General app preferences from Settings > App.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "language": {
          "type": "string",
          "enum": [
            "system",
            "en",
            "ar",
            "bs",
            "zh-Hans",
            "zh-Hant",
            "da",
            "de",
            "es",
            "fr",
            "it",
            "ja",
            "ko",
            "nb",
            "pl",
            "pt-BR",
            "ru",
            "th",
            "tr"
          ],
          "default": "system",
          "description": "Preferred app language."
        },
        "appearance": {
          "type": "string",
          "enum": ["system", "light", "dark"],
          "default": "system",
          "description": "App appearance mode."
        },
        "appIcon": {
          "type": "string",
          "enum": ["automatic", "light", "dark"],
          "default": "automatic",
          "description": "Dock and app switcher icon style."
        },
        "menuBarOnly": {
          "type": "boolean",
          "default": false,
          "description": "Hide the Dock icon and app switcher entry while keeping cmux available from the menu bar."
        },
        "newWorkspacePlacement": {
          "type": "string",
          "enum": ["top", "afterCurrent", "end"],
          "default": "afterCurrent",
          "description": "Where new workspaces are inserted in the sidebar."
        },
        "minimalMode": {
          "type": "boolean",
          "default": false,
          "description": "Hide the workspace title bar and move controls into the sidebar."
        },
        "keepWorkspaceOpenWhenClosingLastSurface": {
          "type": "boolean",
          "default": false,
          "description": "When true, closing the last surface keeps the workspace open."
        },
        "focusPaneOnFirstClick": {
          "type": "boolean",
          "default": true,
          "description": "When cmux is inactive, the first click can activate and focus the clicked pane."
        },
        "preferredEditor": {
          "type": "string",
          "default": "",
          "description": "Custom editor command used by cmux where applicable. Leave empty to use the default."
        },
        "openMarkdownInCmuxViewer": {
          "type": "boolean",
          "default": false,
          "description": "When enabled, Cmd-clicking .md/.markdown/.mkd/.mdx files in the terminal opens them in the cmux markdown viewer panel (with live reload) instead of the preferred editor."
        },
        "reorderOnNotification": {
          "type": "boolean",
          "default": true,
          "description": "Move workspaces with new notifications toward the top."
        },
        "iMessageMode": {
          "type": "boolean",
          "default": false,
          "description": "Move a workspace to the top and show the submitted message when sending an agent prompt."
        },
        "sendAnonymousTelemetry": {
          "type": "boolean",
          "default": true,
          "description": "Allow anonymous telemetry."
        },
        "warnBeforeQuit": {
          "type": "boolean",
          "default": true,
          "description": "Show a confirmation before quitting cmux."
        },
        "renameSelectsExistingName": {
          "type": "boolean",
          "default": true,
          "description": "Select the current name when opening rename flows."
        },
        "commandPaletteSearchesAllSurfaces": {
          "type": "boolean",
          "default": false,
          "description": "Search every surface in the command palette switcher instead of only the active workspace."
        }
      }
    },
    "terminal": {
      "title": "terminal",
      "description": "Terminal presentation settings from Settings > Terminal.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "showScrollBar": {
          "type": "boolean",
          "default": true,
          "description": "Show the right-edge terminal scroll bar when scrollback is available. cmux automatically suppresses it for alternate-screen style TUI surfaces."
        }
      }
    },
    "notifications": {
      "title": "notifications",
      "description": "Notification behavior from Settings > Notifications.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "dockBadge": {
          "type": "boolean",
          "default": true,
          "description": "Show the unread count in the Dock tile."
        },
        "showInMenuBar": {
          "type": "boolean",
          "default": true,
          "description": "Show the menu bar extra."
        },
        "unreadPaneRing": {
          "type": "boolean",
          "default": true,
          "description": "Highlight panes with unread notifications."
        },
        "paneFlash": {
          "type": "boolean",
          "default": true,
          "description": "Flash the focused pane when requested."
        },
        "sound": {
          "type": "string",
          "enum": [
            "default",
            "Basso",
            "Blow",
            "Bottle",
            "Frog",
            "Funk",
            "Glass",
            "Hero",
            "Morse",
            "Ping",
            "Pop",
            "Purr",
            "Sosumi",
            "Submarine",
            "Tink",
            "custom_file",
            "none"
          ],
          "default": "default",
          "description": "Notification sound preset."
        },
        "customSoundFilePath": {
          "type": "string",
          "default": "",
          "description": "Local path to the custom notification sound file."
        },
        "command": {
          "type": "string",
          "default": "",
          "description": "Optional shell command to run alongside notification delivery."
        }
      }
    },
    "sidebar": {
      "title": "sidebar",
      "description": "Sidebar content and metadata visibility from Settings > Sidebar.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "hideAllDetails": {
          "type": "boolean",
          "default": false,
          "description": "Hide all per-workspace detail rows."
        },
        "branchLayout": {
          "type": "string",
          "enum": ["vertical", "inline"],
          "default": "vertical",
          "description": "Show git branch details stacked vertically or inline."
        },
        "showNotificationMessage": {
          "type": "boolean",
          "default": true,
          "description": "Show the latest notification text in the sidebar."
        },
        "showBranchDirectory": {
          "type": "boolean",
          "default": true,
          "description": "Show the workspace working directory."
        },
        "showPullRequests": {
          "type": "boolean",
          "default": true,
          "description": "Show pull request metadata in the sidebar."
        },
        "openPullRequestLinksInCmuxBrowser": {
          "type": "boolean",
          "default": true,
          "description": "Open sidebar pull request links in the embedded cmux browser."
        },
        "openPortLinksInCmuxBrowser": {
          "type": "boolean",
          "default": true,
          "description": "Open sidebar port links in the embedded cmux browser."
        },
        "showSSH": {
          "type": "boolean",
          "default": true,
          "description": "Show SSH connection details."
        },
        "showPorts": {
          "type": "boolean",
          "default": true,
          "description": "Show listening ports."
        },
        "showLog": {
          "type": "boolean",
          "default": true,
          "description": "Show recent log snippets."
        },
        "showProgress": {
          "type": "boolean",
          "default": true,
          "description": "Show progress indicators."
        },
        "showCustomMetadata": {
          "type": "boolean",
          "default": true,
          "description": "Show custom metadata pills."
        }
      }
    },
    "workspaceColors": {
      "title": "workspaceColors",
      "description": "Workspace tab and badge colors from Settings > Workspace Colors.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "indicatorStyle": {
          "type": "string",
          "enum": [
            "leftRail",
            "solidFill",
            "rail",
            "border",
            "wash",
            "lift",
            "typography",
            "washRail",
            "blueWashColorRail"
          ],
          "default": "leftRail",
          "description": "Active workspace indicator style. Legacy aliases are accepted and normalized."
        },
        "selectionColor": {
          "$ref": "#/$defs/colorHexOrNull",
          "default": null,
          "description": "Override the selected workspace background color."
        },
        "notificationBadgeColor": {
          "$ref": "#/$defs/colorHexOrNull",
          "default": null,
          "description": "Override the unread notification badge color."
        },
        "colors": {
          "type": "object",
          "description": "Full named workspace color palette. Include built-in entries you want to keep, remove keys to remove colors, and add more named entries to extend the picker.",
          "default": {
            "Red": "#C0392B",
            "Crimson": "#922B21",
            "Orange": "#A04000",
            "Amber": "#7D6608",
            "Olive": "#4A5C18",
            "Green": "#196F3D",
            "Teal": "#006B6B",
            "Aqua": "#0E6B8C",
            "Blue": "#1565C0",
            "Navy": "#1A5276",
            "Indigo": "#283593",
            "Purple": "#6A1B9A",
            "Magenta": "#AD1457",
            "Rose": "#880E4F",
            "Brown": "#7B3F00",
            "Charcoal": "#3E4B5E"
          },
          "additionalProperties": {
            "$ref": "#/$defs/colorHex"
          }
        }
      }
    },
    "sidebarAppearance": {
      "title": "sidebarAppearance",
      "description": "Sidebar tint settings from Settings > Sidebar Appearance.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "matchTerminalBackground": {
          "type": "boolean",
          "default": false,
          "description": "Use the terminal background instead of the sidebar tint."
        },
        "tintColor": {
          "$ref": "#/$defs/colorHex",
          "default": "#000000",
          "description": "Base sidebar tint color used when light/dark overrides are not set."
        },
        "lightModeTintColor": {
          "$ref": "#/$defs/colorHexOrNull",
          "default": null,
          "description": "Sidebar tint override for light appearance."
        },
        "darkModeTintColor": {
          "$ref": "#/$defs/colorHexOrNull",
          "default": null,
          "description": "Sidebar tint override for dark appearance."
        },
        "tintOpacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.03,
          "description": "Sidebar tint opacity from 0 to 1."
        }
      }
    },
    "automation": {
      "title": "automation",
      "description": "Socket control and automation settings from Settings > Automation.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "socketControlMode": {
          "type": "string",
          "enum": [
            "off",
            "cmuxOnly",
            "automation",
            "password",
            "allowAll",
            "openAccess",
            "fullOpenAccess",
            "notifications",
            "full"
          ],
          "default": "cmuxOnly",
          "description": "Socket control mode. Legacy aliases are accepted and normalized."
        },
        "socketPassword": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": "",
          "description": "Password for password-mode socket access. Use null or an empty string to clear it."
        },
        "claudeCodeIntegration": {
          "type": "boolean",
          "default": true,
          "description": "Enable cmux integration hooks for Claude Code."
        },
        "claudeBinaryPath": {
          "type": "string",
          "default": "",
          "description": "Custom path to the claude binary."
        },
        "portBase": {
          "type": "integer",
          "minimum": 1,
          "default": 9100,
          "description": "Starting value for workspace CMUX_PORT assignments."
        },
        "portRange": {
          "type": "integer",
          "minimum": 1,
          "default": 10,
          "description": "Number of ports reserved per workspace."
        }
      }
    },
    "browser": {
      "title": "browser",
      "description": "Embedded browser settings from Settings > Browser.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "defaultSearchEngine": {
          "type": "string",
          "enum": ["google", "duckduckgo", "bing", "kagi", "startpage"],
          "default": "google",
          "description": "Default search engine for non-URL queries."
        },
        "showSearchSuggestions": {
          "type": "boolean",
          "default": true,
          "description": "Show omnibar search suggestions."
        },
        "theme": {
          "type": "string",
          "enum": ["system", "light", "dark"],
          "default": "system",
          "description": "Embedded browser theme."
        },
        "openTerminalLinksInCmuxBrowser": {
          "type": "boolean",
          "default": true,
          "description": "Open clicked terminal links in the embedded browser."
        },
        "interceptTerminalOpenCommandInCmuxBrowser": {
          "type": "boolean",
          "default": true,
          "description": "Intercept terminal open http(s) commands and route them through the embedded browser."
        },
        "hostsToOpenInEmbeddedBrowser": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Allowlist of hosts that should stay inside the embedded browser."
        },
        "urlsToAlwaysOpenExternally": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Rules that always open matching URLs in the system browser."
        },
        "insecureHttpHostsAllowedInEmbeddedBrowser": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [
            "localhost",
            "127.0.0.1",
            "::1",
            "0.0.0.0",
            "*.localtest.me"
          ],
          "description": "HTTP hosts allowed in the embedded browser without a warning prompt."
        },
        "showImportHintOnBlankTabs": {
          "type": "boolean",
          "default": true,
          "description": "Show the browser import hint on blank tabs."
        },
        "reactGrabVersion": {
          "type": "string",
          "default": "0.1.29",
          "description": "Pinned react-grab version for the browser toolbar helper."
        }
      }
    },
    "shortcuts": {
      "title": "shortcuts",
      "description": "Keyboard shortcut settings from Settings > Keyboard Shortcuts.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "showModifierHoldHints": {
          "type": "boolean",
          "default": true,
          "description": "Show shortcut hint pills while holding Cmd or Ctrl."
        },
        "bindings": {
          "type": "object",
          "default": {},
          "description": "Shortcut overrides keyed by cmux action id. Use a string for a single shortcut, an array for a chord, or an empty string to unbind.",
          "propertyNames": {
            "enum": [
              "openSettings",
              "reloadConfiguration",
              "showHideAllWindows",
              "newWindow",
              "closeWindow",
              "toggleFullScreen",
              "quit",
              "toggleSidebar",
              "newTab",
              "openFolder",
              "reopenPreviousSession",
              "goToWorkspace",
              "commandPalette",
              "sendFeedback",
              "showNotifications",
              "jumpToUnread",
              "focusRightSidebar",
              "switchRightSidebarToFiles",
              "switchRightSidebarToFind",
              "switchRightSidebarToSessions",
              "switchRightSidebarToFeed",
              "switchRightSidebarToDock",
              "triggerFlash",
              "nextSurface",
              "prevSurface",
              "selectSurfaceByNumber",
              "nextSidebarTab",
              "prevSidebarTab",
              "selectWorkspaceByNumber",
              "renameTab",
              "renameWorkspace",
              "editWorkspaceDescription",
              "closeTab",
              "closeOtherTabsInPane",
              "closeWorkspace",
              "reopenClosedBrowserPanel",
              "newSurface",
              "toggleTerminalCopyMode",
              "focusLeft",
              "focusRight",
              "focusUp",
              "focusDown",
              "splitRight",
              "splitDown",
              "toggleSplitZoom",
              "splitBrowserRight",
              "splitBrowserDown",
              "saveFilePreview",
              "openBrowser",
              "focusBrowserAddressBar",
              "browserBack",
              "browserForward",
              "browserReload",
              "browserZoomIn",
              "browserZoomOut",
              "browserZoomReset",
              "find",
              "findInDirectory",
              "findNext",
              "findPrevious",
              "hideFind",
              "useSelectionForFind",
              "toggleBrowserDeveloperTools",
              "showBrowserJavaScriptConsole",
              "toggleReactGrab"
            ]
          },
          "additionalProperties": {
            "$ref": "#/$defs/shortcutBinding"
          }
        }
      }
    }
  },
  "$defs": {
    "colorHex": {
      "type": "string",
      "pattern": "^#[0-9A-Fa-f]{6}$",
      "description": "Uppercase or lowercase 6-digit hex color."
    },
    "colorHexOrNull": {
      "oneOf": [
        {
          "$ref": "#/$defs/colorHex"
        },
        {
          "type": "null"
        }
      ]
    },
    "shortcutBinding": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single-stroke shortcut, for example cmd+n. Use an empty string, none, clear, or unbound to unbind."
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 2,
          "items": {
            "type": "string"
          },
          "description": "Chorded shortcut. Example: [\"ctrl+b\", \"c\"]."
        }
      ]
    }
  }
}