basic-memory 0.22.1__tar.gz → 0.23.0__tar.gz

basic_memory-0.23.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "basic-memory",
+  "interface": {
+    "displayName": "Basic Memory"
+  },
+  "plugins": [
+    {
+      "name": "codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

basic_memory-0.23.0/.agents/skills/cmux/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: cmux
+description: End-user control of cmux topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash). Use when automation needs deterministic placement and navigation in a multi-pane cmux layout.
+---
+
+# cmux Core Control
+
+Non-browser cmux topology and routing.
+
+- **Window**: top-level macOS cmux window.
+- **Workspace**: tab-like group within a window.
+- **Pane**: split container in a workspace.
+- **Surface**: a tab within a pane (terminal or browser panel).
+
+## Fast start
+
+```bash
+cmux identify --json                              # current caller context
+cmux list-windows / list-workspaces / list-panes
+cmux list-pane-surfaces --pane pane:1
+cmux new-workspace
+cmux new-split right --panel pane:1
+cmux move-surface --surface surface:7 --pane pane:2 --focus true
+cmux split-off --surface surface:7 right
+cmux reorder-surface --surface surface:7 --before surface:3
+
+# workspace context-menu actions (color, description, rename, pin, ...)
+cmux workspace-action --action set-color --color Blue
+cmux workspace-action --action set-description --description "Ship checklist"
+
+# attention cue
+cmux trigger-flash --surface surface:7
+```
+
+## Handle model
+
+Output defaults to short refs (`window:N`, `workspace:N`, `pane:N`, `surface:N`). UUIDs are accepted as input; request UUID output only when needed with `--id-format uuids|both`.
+
+## Settings
+
+cmux-owned settings live in `~/.config/cmux/cmux.json`. `cmux docs settings` prints the docs URL, schema URL, raw GitHub resources, cmux.json paths, and reload command. `cmux settings`, `cmux settings cmux-json`, and `cmux settings shortcuts` open the UI.
+
+`cmux reload-config` reloads both `cmux.json` and `~/.config/ghostty/config`, refreshing terminals in place with no app restart.
+
+Terminal rendering (font, cursor style, theme, scrollback, `background-opacity`, `background-blur`) belongs in Ghostty config, not cmux settings. Everything else (app behavior, sidebar, notifications, browser behavior, automation, workspace colors, cmux-owned shortcuts) is cmux settings. Before editing, copy any existing `cmux.json` to a timestamped `.bak` next to it. Legacy `~/.config/cmux/settings.json` and `~/Library/Application Support/com.cmuxterm.app/settings.json` are read only as fallback for missing keys.
+
+## Deep-dive references
+
+| Reference | When to Use |
+|-----------|-------------|
+| [references/handles-and-identify.md](references/handles-and-identify.md) | Handle syntax, self-identify, caller targeting |
+| [references/windows-workspaces.md](references/windows-workspaces.md) | Window/workspace lifecycle, reorder/move, and context-menu actions (color, description, rename) |
+| [references/panes-surfaces.md](references/panes-surfaces.md) | Splits, surfaces, move/reorder, focus routing |
+| [references/trigger-flash-and-health.md](references/trigger-flash-and-health.md) | Flash cue and surface health checks |
+| [../cmux-workspace/SKILL.md](../cmux-workspace/SKILL.md) | Current caller workspace rules and non-disruptive automation |
+| [../cmux-settings/SKILL.md](../cmux-settings/SKILL.md) | Safe cmux.json settings edits and validation |
+| [../cmux-browser/SKILL.md](../cmux-browser/SKILL.md) | Browser automation on surface-backed webviews |
+| [../cmux-markdown/SKILL.md](../cmux-markdown/SKILL.md) | Markdown viewer panel with live file watching |

basic_memory-0.23.0/.agents/skills/cmux/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Core"
+  short_description: "Control windows/workspaces/panes/surfaces and routing with cmux CLI."
+  default_prompt: "Use this skill to inspect and manipulate cmux topology: identify context, target handles, create/focus/move/reorder windows/workspaces/panes/surfaces, and use trigger-flash for visual confirmation."

basic_memory-0.23.0/.agents/skills/cmux/references/handles-and-identify.md

@@ -0,0 +1,12 @@
+# Handles and Identify
+
+Most v2-backed commands accept a UUID, a short ref (`window:N`, `workspace:N`, `pane:N`, `surface:N`), or an index where legacy index-based commands still allow it.
+
+```bash
+cmux identify --json                                  # focused topology + caller resolution
+cmux identify --workspace workspace:2                 # route relative actions from a known anchor
+cmux identify --workspace workspace:2 --surface surface:8
+
+cmux --json --id-format both identify                 # refs plus UUIDs
+cmux --json --id-format uuids identify
+```

basic_memory-0.23.0/.agents/skills/cmux/references/panes-surfaces.md

@@ -0,0 +1,25 @@
+# Panes and Surfaces
+
+```bash
+# inspect
+cmux list-panes
+cmux list-pane-surfaces --pane pane:1
+
+# create
+cmux new-split right --panel pane:1
+cmux new-surface --type terminal --pane pane:1
+cmux new-surface --type browser --pane pane:1 --url https://example.com
+
+# focus and close
+cmux focus-pane --pane pane:2
+cmux focus-panel --panel surface:7
+cmux close-surface --surface surface:7
+
+# move and reorder
+cmux move-surface --surface surface:7 --pane pane:2 --focus true
+cmux move-surface --surface surface:7 --workspace workspace:2 --window window:1 --after surface:4
+cmux split-off --surface surface:7 right
+cmux reorder-surface --surface surface:7 --before surface:3
+```
+
+Surface identity is stable across move, reorder, and split-off. Layout commands are focus-neutral by default; pass `--focus true` only when the moved or created surface should be selected.

basic_memory-0.23.0/.agents/skills/cmux/references/trigger-flash-and-health.md

@@ -0,0 +1,15 @@
+# Trigger Flash and Surface Health
+
+Flash a surface or workspace for visual confirmation in the UI:
+
+```bash
+cmux trigger-flash --surface surface:7
+cmux trigger-flash --workspace workspace:2
+```
+
+Detect hidden, detached, or non-windowed surfaces before routing focused input when UI state may be stale:
+
+```bash
+cmux surface-health
+cmux surface-health --workspace workspace:2
+```

basic_memory-0.23.0/.agents/skills/cmux/references/windows-workspaces.md

@@ -0,0 +1,35 @@
+# Windows and Workspaces
+
+```bash
+# inspect
+cmux list-windows
+cmux current-window
+cmux list-workspaces
+cmux current-workspace
+
+# lifecycle
+cmux new-window
+cmux focus-window --window window:2
+cmux close-window --window window:2
+cmux new-workspace
+cmux select-workspace --workspace workspace:4
+cmux close-workspace --workspace workspace:4
+
+# reorder and move
+cmux reorder-workspace --workspace workspace:4 --before workspace:2
+cmux move-workspace-to-window --workspace workspace:4 --window window:1
+```
+
+## Context-Menu Actions
+
+`cmux workspace-action` runs the workspace right-click actions (color, description, rename, pin, read state, ordering). Defaults to the caller's workspace; override with `--workspace <id|ref|index>`.
+
+```bash
+cmux workspace-action --action set-color --color Blue      # name or #RRGGBB hex
+cmux workspace-action --action set-description --description "Ship checklist"
+cmux workspace-action --action rename --title "infra"
+cmux workspace-action --action pin
+cmux workspace-action --action clear-color
+```
+
+Other actions: `unpin`, `clear-name`, `clear-description`, `mark-read`/`mark-unread`, `move-up`/`move-down`/`move-top`, `close-others`/`close-above`/`close-below`. Named colors: Red, Crimson, Orange, Amber, Olive, Green, Teal, Aqua, Blue, Navy, Indigo, Purple, Magenta, Rose, Brown, Charcoal. `set-color` tints a single workspace (stored as workspace state); the `workspaceColors` block in `cmux.json` defines the shared palette and selection/badge colors, not per-workspace assignments.

basic_memory-0.23.0/.agents/skills/cmux-markdown/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cmux-markdown
+description: Open markdown files in a formatted viewer panel with live reload. Use when you need to display plans, documentation, or notes alongside the terminal with rich rendering (headings, code blocks, tables, lists).
+---
+
+# Markdown Viewer with cmux
+
+Write a `.md` file, open it in a panel, and the panel re-renders whenever the file changes on disk. Use it for agent plans and task lists alongside the terminal, documentation and changelogs while working, and notes another process updates progressively.
+
+```bash
+cmux markdown open plan.md                              # split next to the current terminal
+cmux markdown open /path/to/PLAN.md
+cmux markdown open design.md --workspace workspace:2    # also --surface, --window
+```
+
+Relative paths resolve against the caller's cwd and `~` expands; the resolved absolute path comes back in the output.
+
+## Agent usage
+
+Write the full plan file first, then open it, so the panel never shows a partially written file. After that, overwrite or append freely: each write triggers a re-render, and atomic replacement (editor saves, `sed -i`, VS Code) is handled.
+
+To instruct coding agents in a project, add to its `AGENTS.md`:
+
+```markdown
+## Plan Display
+
+When creating a plan or task list, write it to a `.md` file and open it in cmux:
+
+    cmux markdown open plan.md
+
+The panel renders markdown with rich formatting and auto-updates when the file changes.
+```
+
+## Rendering
+
+Headings h1-h6 (dividers on h1/h2), fenced code blocks in monospace, inline code with a highlighted background, tables with alternating row colors, nested ordered and unordered lists, blockquotes with a left border, bold/italic/strikethrough, clickable links, horizontal rules, and inline images. Light and dark mode both supported.
+
+## Deep-dive references
+
+| Reference | When to Use |
+|-----------|-------------|
+| [references/commands.md](references/commands.md) | Full command syntax, options, output shape, panel behavior |
+| [references/live-reload.md](references/live-reload.md) | File watching, atomic writes, unavailable-file state, performance |

basic_memory-0.23.0/.agents/skills/cmux-markdown/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Markdown Viewer"
+  short_description: "Open markdown files in a formatted panel with live reload alongside the terminal."
+  default_prompt: "Use this skill to display markdown plans, docs, or notes in a cmux panel: write to a .md file, run 'cmux markdown open <path>', and the panel auto-updates when the file changes."

basic_memory-0.23.0/.agents/skills/cmux-markdown/references/commands.md

@@ -0,0 +1,29 @@
+# Command Reference (cmux Markdown)
+
+```bash
+cmux markdown open <path>
+cmux markdown <path>          # shorthand, "open" is implicit
+cmux markdown --help
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--workspace <id\|ref\|index>` | Target workspace | `$CMUX_WORKSPACE_ID` |
+| `--surface <id\|ref\|index>` | Source surface to split from | Focused surface |
+| `--window <id\|ref>` | Target window | Current window |
+
+## Output
+
+```
+OK surface=surface:8 pane=pane:3 path=/absolute/path/to/file.md
+```
+
+`--json` returns `window_id`, `workspace_id`, `pane_id`, `surface_id`, and `path`.
+
+## Panel behavior
+
+The panel opens as a horizontal split to the right of the source surface. The tab shows the filename and a document icon; the file path appears as a breadcrumb at the top. Content is read-only with text selection enabled.
+
+Markdown panels are saved and restored across sessions and re-read the file from disk on restore. A panel is not recreated if the file no longer exists at restore time.
+
+See also [live-reload.md](live-reload.md).

basic_memory-0.23.0/.agents/skills/cmux-markdown/references/live-reload.md

@@ -0,0 +1,19 @@
+# Live Reload Behavior
+
+The panel watches the file with a kernel-level watcher (`DispatchSource` with `O_EVTONLY`) for write, extend, delete, and rename events, and re-renders on change.
+
+## Supported write patterns
+
+Direct writes (`echo >>`), editor saves, atomic replace (write temp then rename), `sed -i`, VS Code/IDE saves, and progressive agent writes all work. Most of these are atomic replace under the hood.
+
+## Atomic file replacement
+
+An atomic replace shows up as a delete event followed by a new file at the same path. The panel detects it, re-reads immediately (in case the rename already landed), waits 500 ms and checks again if the file is missing, then reconnects the watcher to the new inode.
+
+## File unavailable state
+
+If the file is deleted and does not reappear within the retry window, the panel shows a "file unavailable" state with the original path and stays open until the user closes it. It does not reconnect if the file later reappears; close and reopen the panel.
+
+## Performance
+
+Re-reads are dispatched to the main thread and run synchronously, so files over ~100KB can cause brief UI hitches during re-render; split very large documents. The watcher itself runs on a low-priority background queue with negligible CPU impact.

basic_memory-0.23.0/.agents/skills/cmux-settings/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cmux-settings
+description: "View and edit cmux settings in ~/.config/cmux/cmux.json. Use when the user wants to change cmux preferences (appearance, sidebar, notifications, automation, browser, shortcuts), set a value by JSON path, validate the file, open it in an editor, or look up which keys cmux recognizes. Triggers on '/cmux-settings', 'change cmux setting', 'set <something> in cmux', 'cmux config', 'cmux.json', or 'rebind a cmux shortcut'."
+---
+
+# cmux-settings
+
+cmux reads user settings from `~/.config/cmux/cmux.json` (JSONC). A file watcher applies changes on save, no restart. Legacy `~/.config/cmux/settings.json` is read only as a fallback for keys absent from `cmux.json`.
+
+Schema: `https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json`. The authoritative path list is `Sources/CmuxSettingsJSONPathSupport.swift`; the installed skill carries a generated copy in `references/all-keys.md`. Settings sections are `app`, `terminal`, `notifications`, `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`, `shortcuts`. Non-settings sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`) share the same file.
+
+## Helper script
+
+Use the bundled helper for every read/write. It strips JSONC comments, writes atomically, and validates keys against the schema.
+
+```bash
+skills/cmux-settings/scripts/cmux-settings <subcommand>            # from a cmux checkout
+~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>   # installed Codex skill
+```
+
+The rest of this doc assumes it is on `$PATH` as `cmux-settings`; from a checkout, `export PATH="$PWD/skills/cmux-settings/scripts:$PATH"`.
+
+| Command | What it does |
+|---|---|
+| `cmux-settings path` | Print the config path. |
+| `cmux-settings dump` | Print the raw file (preserves comments). |
+| `cmux-settings dump --no-comments` | Print the parsed JSON. |
+| `cmux-settings get <a.b.c>` | Print value at dotted JSON path. |
+| `cmux-settings set <a.b.c> <value>` | Set value. `<value>` is parsed as JSON (`true`, `42`, `"text"`, `[…]`, `{…}`); unquoted plain words are stored as strings. |
+| `cmux-settings unset <a.b.c>` | Delete key, reverting to the in-app default. |
+| `cmux-settings list-supported` | List every settings JSON path the app recognizes. |
+| `cmux-settings validate` | Parse the file and flag unknown settings keys. |
+| `cmux-settings open` | Open `cmux.json` in `$EDITOR`, VS Code, Cursor, or TextEdit. |
+
+`--file <path>` overrides the target file, useful for `--file ~/.config/cmux/settings.json`.
+
+## Workflow
+
+1. Look up the key when the user named a setting in plain English:
+   ```bash
+   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
+   ```
+2. Set it. JSON literals must be valid JSON.
+   ```bash
+   cmux-settings set sidebarAppearance.matchTerminalBackground true
+   cmux-settings set app.appearance dark
+   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
+   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
+   ```
+3. Read back and `cmux-settings validate`.
+4. Tell the user it auto-reloaded, and that `cmux-settings unset <key>` reverts it.
+
+## Quick reference
+
+- Appearance: `app.appearance` (`"system" | "light" | "dark"`), `app.appIcon`, `app.menuBarOnly`, `app.minimalMode`.
+- Sidebar tint: `sidebarAppearance.matchTerminalBackground`, `.tintColor`, `.tintOpacity` (0..1).
+- Sidebar details: `sidebar.hideAllDetails`, `.showBranchDirectory`, `.showPullRequests`, `.showPorts`, `.showLog`.
+- Notifications: `notifications.dockBadge`, `.sound` (enum including `"none"`, `"custom_file"`), `.customSoundFilePath`, `.hooks` (array).
+- Browser: `browser.defaultSearchEngine`, `.theme`, `.openTerminalLinksInCmuxBrowser`, `.hostsToOpenInEmbeddedBrowser`.
+- Automation: `automation.socketControlMode` (`off | cmuxOnly | automation | password | allowAll`), `.portBase`, `.portRange`.
+- Shortcuts: `shortcuts.bindings.<actionId>` = `"cmd+b"`, `["ctrl+b","c"]`, `null`, or `""` to unbind. Action ids in [references/shortcut-actions.md](references/shortcut-actions.md).
+
+Full list of settings, defaults, and descriptions: `cmux-settings list-supported` or [references/all-keys.md](references/all-keys.md).
+
+## Rules
+
+- Only edit `cmux.json`. Never `settings.json` unless the user explicitly asks; it is legacy and read only when a key is absent from `cmux.json`.
+- Never tell the user to restart cmux. The file watcher reloads on save.
+- Always `cmux-settings validate` after a bulk edit. Unknown keys mean the user pasted a key the app does not consume.
+- Do not blindly overwrite `actions`, `ui`, `commands`, `vault`, or `rightSidebar`; they share the file and hold hand-tuned non-settings config.
+- Shortcut action ids must match the schema enum. Look them up before binding.
+- Colors are `#RRGGBB`; opacities are `0..1`.
+- Translate app-level phrasing ("Settings > Notifications > Dock badge") to the JSON path first; `web/app/[locale]/(landing)/docs/configuration/page.tsx` mirrors the schema 1:1.

basic_memory-0.23.0/.agents/skills/cmux-settings/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Settings"
+  short_description: "Inspect, edit, validate, and reload cmux.json settings."
+  default_prompt: "Use this skill to change cmux settings safely: map user-facing preferences to cmux.json paths, edit with the bundled helper, validate recognized keys, and rely on cmux's live config reload."

basic_memory-0.23.0/.agents/skills/cmux-settings/references/all-keys.md

@@ -0,0 +1,140 @@
+# All settings keys
+
+Auto-generated from `web/data/cmux.schema.json`. For the rendered docs, see `https://cmux.com/docs/configuration`.
+
+## app
+
+General app preferences from Settings > App.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `app.language` | `"system"` or `"en"` or `"ar"` or `"bs"` or `"zh-Hans"` or `"zh-Hant"` or `"da"` or `"de"` or `"es"` or `"fr"` or `"it"` or `"ja"` or `"ko"` or `"nb"` or `"pl"` or `"pt-BR"` or `"ru"` or `"th"` or `"tr"` | `"system"` | Preferred app language. |
+| `app.appearance` | `"system"` or `"light"` or `"dark"` | `"system"` | App appearance mode. |
+| `app.appIcon` | `"automatic"` or `"light"` or `"dark"` | `"automatic"` | Dock and app switcher icon style. |
+| `app.menuBarOnly` | boolean | `false` | Hide the Dock icon and app switcher entry while keeping cmux available from the menu bar. |
+| `app.newWorkspacePlacement` | `"top"` or `"afterCurrent"` or `"end"` | `"afterCurrent"` | Where new workspaces are inserted in the sidebar. |
+| `app.workspaceInheritWorkingDirectory` | boolean | `true` | When true, new workspaces inherit the current workspace working directory. When false, new workspaces use Ghostty's working-directory setting instead. |
+| `app.minimalMode` | boolean | `false` | Hide the workspace title bar and move controls into the sidebar. |
+| `app.keepWorkspaceOpenWhenClosingLastSurface` | boolean | `false` | When true, closing the last surface keeps the workspace open. |
+| `app.focusPaneOnFirstClick` | boolean | `true` | When cmux is inactive, the first click can activate and focus the clicked pane. |
+| `app.preferredEditor` | string | `""` | Custom editor command used when Cmd-click file previews are disabled or a file is unsupported. Leave empty to use the default. |
+| `app.openSupportedFilesInCmux` | boolean | `true` | When enabled, Cmd-clicking readable local files opens supported previews in cmux, including text, code, PDFs, images, audio, video, and Quick Look files. Preview headers include an Open With menu based on the user's default and compatible macOS apps for that file. |
+| `app.openMarkdownInCmuxViewer` | boolean | `true` | When enabled, Cmd-clicking .md/.markdown/.mkd/.mdx files opens the rendered cmux markdown viewer panel (with live reload) instead of the generic file preview. |
+| `app.reorderOnNotification` | boolean | `true` | Move workspaces with new notifications toward the top. |
+| `app.iMessageMode` | boolean | `false` | Move a workspace to the top and show the submitted message when sending an agent prompt. |
+| `app.sendAnonymousTelemetry` | boolean | `true` | Allow anonymous telemetry. |
+| `app.warnBeforeQuit` | boolean | `true` | Show a confirmation before quitting cmux. |
+| `app.warnBeforeClosingTab` | boolean | `true` | Show a confirmation before closing a tab. |
+| `app.renameSelectsExistingName` | boolean | `true` | Select the current name when opening rename flows. |
+| `app.commandPaletteSearchesAllSurfaces` | boolean | `false` | Search every surface in the command palette switcher instead of only the active workspace. |
+
+## terminal
+
+Terminal presentation settings from Settings > Terminal.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `terminal.showScrollBar` | boolean | `true` | Show the right-edge terminal scroll bar when scrollback is available. cmux automatically suppresses it for alternate-screen style TUI surfaces. |
+| `terminal.autoResumeAgentSessions` | boolean | `true` | Automatically run agent resume commands for restored terminal sessions when cmux reopens after quit. Set false to restore panes while keeping Claude Code, Codex, OpenCode, and other saved agent sessions idle until you resume them manually. |
+
+## notifications
+
+Notification behavior from Settings > Notifications.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `notifications.dockBadge` | boolean | `true` | Show the unread count in the Dock tile. |
+| `notifications.showInMenuBar` | boolean | `true` | Show the menu bar extra. |
+| `notifications.unreadPaneRing` | boolean | `true` | Highlight panes with unread notifications. |
+| `notifications.paneFlash` | boolean | `true` | Flash the focused pane when requested. |
+| `notifications.sound` | `"default"` or `"Basso"` or `"Blow"` or `"Bottle"` or `"Frog"` or `"Funk"` or `"Glass"` or `"Hero"` or `"Morse"` or `"Ping"` or `"Pop"` or `"Purr"` or `"Sosumi"` or `"Submarine"` or `"Tink"` or `"custom_file"` or `"none"` | `"default"` | Notification sound preset. |
+| `notifications.customSoundFilePath` | string | `""` | Local path to the custom notification sound file. |
+| `notifications.command` | string | `""` | Optional shell command to run alongside notification delivery. |
+| `notifications.hooksMode` | `"append"` or `"replace"` | `"append"` | Controls whether project-local notification hooks append to inherited hooks or replace them. |
+| `notifications.hooks` | array<object> | `[]` | Composable shell hooks that receive notification policy JSON on stdin and return updated policy JSON on stdout. |
+
+## sidebar
+
+Sidebar content and metadata visibility from Settings > Sidebar.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `sidebar.hideAllDetails` | boolean | `false` | Hide all per-workspace detail rows. |
+| `sidebar.showWorkspaceDescription` | boolean | `true` | Show custom workspace descriptions in the sidebar. |
+| `sidebar.branchLayout` | `"vertical"` or `"inline"` | `"vertical"` | Show git branch details stacked vertically or inline. |
+| `sidebar.showNotificationMessage` | boolean | `true` | Show the latest notification text in the sidebar. |
+| `sidebar.showBranchDirectory` | boolean | `true` | Show the workspace working directory. |
+| `sidebar.showPullRequests` | boolean | `true` | Show pull request metadata in the sidebar. |
+| `sidebar.makePullRequestsClickable` | boolean | `true` | Allow sidebar pull request metadata to open links when clicked. |
+| `sidebar.openPullRequestLinksInCmuxBrowser` | boolean | `true` | Open sidebar pull request links in the embedded cmux browser. |
+| `sidebar.openPortLinksInCmuxBrowser` | boolean | `true` | Open sidebar port links in the embedded cmux browser. |
+| `sidebar.showSSH` | boolean | `true` | Show SSH connection details. |
+| `sidebar.showPorts` | boolean | `true` | Show listening ports. |
+| `sidebar.showLog` | boolean | `true` | Show recent log snippets. |
+| `sidebar.showProgress` | boolean | `true` | Show progress indicators. |
+| `sidebar.showCustomMetadata` | boolean | `true` | Show custom metadata pills. |
+
+## workspaceColors
+
+Workspace tab and badge colors from Settings > Workspace Colors.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `workspaceColors.indicatorStyle` | `"leftRail"` or `"solidFill"` or `"rail"` or `"border"` or `"wash"` or `"lift"` or `"typography"` or `"washRail"` or `"blueWashColorRail"` | `"leftRail"` | Active workspace indicator style. Legacy aliases are accepted and normalized. |
+| `workspaceColors.selectionColor` | colorHexOrNull | `null` | Override the selected workspace background color. |
+| `workspaceColors.notificationBadgeColor` | colorHexOrNull | `null` | Override the unread notification badge color. |
+| `workspaceColors.colors` | object | `{"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"}` | 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. |
+| `workspaceColors.paletteOverrides` | object | `{}` | Legacy workspace color overrides for built-in palette names. Prefer workspaceColors.colors for new configs. |
+| `workspaceColors.customColors` | array<colorHex> | `[]` | Legacy list of custom workspace colors. Prefer workspaceColors.colors for new configs. |
+
+## sidebarAppearance
+
+Sidebar tint settings from Settings > Sidebar Appearance.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `sidebarAppearance.matchTerminalBackground` | boolean | `false` | Use the terminal background instead of the sidebar tint. |
+| `sidebarAppearance.tintColor` | colorHex | `"#000000"` | Base sidebar tint color used when light/dark overrides are not set. |
+| `sidebarAppearance.lightModeTintColor` | colorHexOrNull | `null` | Sidebar tint override for light appearance. |
+| `sidebarAppearance.darkModeTintColor` | colorHexOrNull | `null` | Sidebar tint override for dark appearance. |
+| `sidebarAppearance.tintOpacity` | number | `0.03` | Sidebar tint opacity from 0 to 1. Note: this only controls the sidebar tint, not terminal/window transparency. For terminal background transparency or blur, set `background-opacity` and `background-blur` in `~/.config/ghostty/config` and run `cmux reload-config`. |
+
+## automation
+
+Socket control and automation settings from Settings > Automation.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `automation.socketControlMode` | `"off"` or `"cmuxOnly"` or `"automation"` or `"password"` or `"allowAll"` or `"openAccess"` or `"fullOpenAccess"` or `"notifications"` or `"full"` | `"cmuxOnly"` | Socket control mode. Legacy aliases are accepted and normalized. |
+| `automation.socketPassword` | string or null | `""` | Password for password-mode socket access. Use null or an empty string to clear it. |
+| `automation.claudeCodeIntegration` | boolean | `true` | Enable cmux integration hooks for Claude Code. |
+| `automation.claudeBinaryPath` | string | `""` | Custom path to the claude binary. |
+| `automation.cursorIntegration` | boolean | `true` | Enable cmux integration hooks for Cursor. |
+| `automation.geminiIntegration` | boolean | `true` | Enable cmux integration hooks for Gemini. |
+| `automation.portBase` | integer | `9100` | Starting value for workspace CMUX_PORT assignments. |
+| `automation.portRange` | integer | `10` | Number of ports reserved per workspace. |
+
+## browser
+
+Embedded browser settings from Settings > Browser.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `browser.defaultSearchEngine` | `"google"` or `"duckduckgo"` or `"bing"` or `"kagi"` or `"startpage"` | `"google"` | Default search engine for non-URL queries. |
+| `browser.showSearchSuggestions` | boolean | `true` | Show omnibar search suggestions. |
+| `browser.theme` | `"system"` or `"light"` or `"dark"` | `"system"` | Embedded browser theme. |
+| `browser.openTerminalLinksInCmuxBrowser` | boolean | `true` | Open clicked terminal links in the embedded browser. |
+| `browser.interceptTerminalOpenCommandInCmuxBrowser` | boolean | `true` | Intercept terminal open http(s) commands and route them through the embedded browser. |
+| `browser.hostsToOpenInEmbeddedBrowser` | array<string> | `[]` | Allowlist of hosts that should stay inside the embedded browser. |
+| `browser.urlsToAlwaysOpenExternally` | array<string> | `[]` | Rules that always open matching URLs in the system browser. |
+| `browser.insecureHttpHostsAllowedInEmbeddedBrowser` | array<string> | `["localhost", "*.localhost", "127.0.0.1", "::1", "0.0.0.0", "*.localtest.me"]` | HTTP hosts allowed in the embedded browser without a warning prompt. |
+| `browser.showImportHintOnBlankTabs` | boolean | `true` | Show the browser import hint on blank tabs. |
+| `browser.reactGrabVersion` | string | `"0.1.29"` | Pinned react-grab version for the browser toolbar helper. |
+
+## shortcuts
+
+Keyboard shortcut settings from Settings > Keyboard Shortcuts.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `shortcuts.bindings` | object | `{}` | Shortcut overrides keyed by cmux action id. Use a string for a single shortcut, an array for a chord, null, an empty string, none, clear, unbound, or disabled to unbind. |