From dc95e7ede8668d3e16d5535e1e201e03984c1a46 Mon Sep 17 00:00:00 2001 From: Lawrence Chen Date: Fri, 15 May 2026 16:56:26 -0700 Subject: [PATCH 1/4] Add customization and diagnostics skills --- skills/cmux-customization/SKILL.md | 115 +++++++++++ skills/cmux-customization/agents/openai.yaml | 4 + skills/cmux-debug-windows/SKILL.md | 51 ----- skills/cmux-debug-windows/agents/openai.yaml | 4 - .../scripts/debug_windows_snapshot.sh | 190 ------------------ skills/cmux-diagnostics/SKILL.md | 84 ++++++++ skills/cmux-diagnostics/agents/openai.yaml | 4 + .../cmux-diagnostics/scripts/cmux-diagnostics | 180 +++++++++++++++++ web/app/[locale]/docs/skills/page.tsx | 64 +++--- web/messages/en.json | 35 ++-- web/messages/ja.json | 35 ++-- 11 files changed, 450 insertions(+), 316 deletions(-) create mode 100644 skills/cmux-customization/SKILL.md create mode 100644 skills/cmux-customization/agents/openai.yaml delete mode 100644 skills/cmux-debug-windows/SKILL.md delete mode 100644 skills/cmux-debug-windows/agents/openai.yaml delete mode 100755 skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh create mode 100644 skills/cmux-diagnostics/SKILL.md create mode 100644 skills/cmux-diagnostics/agents/openai.yaml create mode 100755 skills/cmux-diagnostics/scripts/cmux-diagnostics diff --git a/skills/cmux-customization/SKILL.md b/skills/cmux-customization/SKILL.md new file mode 100644 index 000000000000..0e0c4946a0ad --- /dev/null +++ b/skills/cmux-customization/SKILL.md @@ -0,0 +1,115 @@ +--- +name: cmux-customization +description: "Customize cmux for an end user. Use when changing cmux.json actions, custom commands, workspace layouts, Command Palette entries, surface toolbar buttons, shortcuts, notifications, browser routing, appearance, or Ghostty-backed terminal preferences." +--- + +# cmux Customization + +Use this skill for user-facing cmux customization. Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion. + +## 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. + +## 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. + +## 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" } + } + ] + } + } +} +``` + +## 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. + +## 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. diff --git a/skills/cmux-customization/agents/openai.yaml b/skills/cmux-customization/agents/openai.yaml new file mode 100644 index 000000000000..8cb9572964e1 --- /dev/null +++ b/skills/cmux-customization/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "cmux Customization" + short_description: "Customize cmux actions, settings, and layouts." + default_prompt: "Use $cmux-customization to add a project-specific cmux action and validate the config." diff --git a/skills/cmux-debug-windows/SKILL.md b/skills/cmux-debug-windows/SKILL.md deleted file mode 100644 index 885c5f49df41..000000000000 --- a/skills/cmux-debug-windows/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: cmux-debug-windows -description: Manage cmux debug windows and related debug menu wiring for Sidebar Debug, Background Debug, and Menu Bar Extra Debug. Use this when the user asks to open/tune these debug controls, add or adjust Debug menu entries, or capture/copy a combined debug config snapshot. ---- - -# cmux Debug Windows - -Keep this workflow focused on existing debug windows and menu entries. Do not add a new utility/debug control window unless the user asks explicitly. - -## Workflow - -1. Verify debug menu wiring in `Sources/cmuxApp.swift` under `CommandMenu("Debug")`. - - Menu path in app: `Debug` → `Debug Windows` → window entry. - - The `Debug` menu only exists in DEBUG builds (`./scripts/reload.sh --tag ...`). - - Release builds (`reloadp.sh`, `reloads.sh`) do not show this menu. -2. Keep these actions available in `Menu("Debug Windows")`: -- `Sidebar Debug…` -- `Background Debug…` -- `Menu Bar Extra Debug…` -- `Open All Debug Windows` -3. Reuse existing per-window copy buttons (`Copy Config`) in each debug window before adding new UI. -4. For one combined payload, run: -```bash -skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh --copy -``` -5. After code edits, run build + tagged reload: -```bash -xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination 'platform=macOS' build -./scripts/reload.sh --tag -``` - -## Key Files - -- `Sources/cmuxApp.swift`: Debug menu entries and debug window controllers/views. -- `Sources/AppDelegate.swift`: Menu bar extra debug settings payload and defaults keys. - -## Script - -- `scripts/debug_windows_snapshot.sh` - -Purpose: -- Reads current debug-related defaults values. -- Prints one combined snapshot for sidebar/background/menu bar extra. -- Optionally copies it to clipboard. - -Examples: -```bash -skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh -skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh --copy -skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh --domain --copy -``` diff --git a/skills/cmux-debug-windows/agents/openai.yaml b/skills/cmux-debug-windows/agents/openai.yaml deleted file mode 100644 index 39e648dd09b7..000000000000 --- a/skills/cmux-debug-windows/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "cmux Debug Windows" - short_description: "Tune cmux debug windows and copy snapshots." - default_prompt: "Use this skill to manage cmux sidebar/background/menu-bar debug windows, keep Debug menu wiring clean, and capture copyable debug snapshots." diff --git a/skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh b/skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh deleted file mode 100755 index 7798e8e7ac1e..000000000000 --- a/skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh +++ /dev/null @@ -1,190 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -usage() { - cat <<'USAGE' -Usage: debug_windows_snapshot.sh [--domain ] [--copy] - -Collect Sidebar Debug, Background Debug, Menu Bar Extra, and Browser DevTools debug values -from macOS defaults and print a combined payload. Use --copy to also copy the payload. - -Examples: - debug_windows_snapshot.sh - debug_windows_snapshot.sh --copy - debug_windows_snapshot.sh --domain dev.manaflow.cmux --copy -USAGE -} - -domain="" -copy_flag=0 - -while [[ $# -gt 0 ]]; do - case "$1" in - --domain) - shift - [[ $# -gt 0 ]] || { echo "Missing value for --domain" >&2; exit 1; } - domain="$1" - ;; - --copy) - copy_flag=1 - ;; - -h|--help) - usage - exit 0 - ;; - *) - echo "Unknown argument: $1" >&2 - usage >&2 - exit 1 - ;; - esac - shift -done - -discover_domain() { - defaults domains 2>/dev/null \ - | tr ',' '\n' \ - | tr -d ' ' \ - | grep -E 'cmux' \ - | head -n1 || true -} - -read_value() { - local key="$1" - local fallback="$2" - local value - value=$(defaults read "$domain" "$key" 2>/dev/null || true) - if [[ -z "$value" ]]; then - printf '%s' "$fallback" - else - printf '%s' "$value" - fi -} - -format_number() { - local raw="$1" - local precision="$2" - if [[ "$raw" =~ ^-?[0-9]+([.][0-9]+)?$ ]]; then - printf "%.*f" "$precision" "$raw" - else - printf "%.*f" "$precision" 0 - fi -} - -if [[ -z "$domain" ]]; then - domain="$(discover_domain)" -fi - -if [[ -z "$domain" ]]; then - echo "Could not auto-detect a cmux defaults domain. Pass --domain ." >&2 - exit 1 -fi - -if ! defaults domains 2>/dev/null | tr ',' '\n' | tr -d ' ' | grep -Fxq "$domain"; then - echo "Defaults domain '$domain' was not found on this machine." >&2 - exit 1 -fi - -sidebarPreset="$(read_value sidebarPreset nativeSidebar)" -sidebarMaterial="$(read_value sidebarMaterial sidebar)" -sidebarBlendMode="$(read_value sidebarBlendMode behindWindow)" -sidebarState="$(read_value sidebarState followWindow)" -sidebarBlurOpacity="$(format_number "$(read_value sidebarBlurOpacity 0.79)" 2)" -sidebarTintHex="$(read_value sidebarTintHex '#101010')" -sidebarTintOpacity="$(format_number "$(read_value sidebarTintOpacity 0.54)" 2)" -sidebarCornerRadius="$(format_number "$(read_value sidebarCornerRadius 0.0)" 1)" -sidebarActiveTabIndicatorStyle="$(read_value sidebarActiveTabIndicatorStyle solidFill)" -shortcutHintSidebarXOffset="$(format_number "$(read_value shortcutHintSidebarXOffset 0.0)" 1)" -shortcutHintSidebarYOffset="$(format_number "$(read_value shortcutHintSidebarYOffset 0.0)" 1)" -shortcutHintTitlebarXOffset="$(format_number "$(read_value shortcutHintTitlebarXOffset 4.0)" 1)" -shortcutHintTitlebarYOffset="$(format_number "$(read_value shortcutHintTitlebarYOffset 0.0)" 1)" -shortcutHintPaneTabXOffset="$(format_number "$(read_value shortcutHintPaneTabXOffset 0.0)" 1)" -shortcutHintPaneTabYOffset="$(format_number "$(read_value shortcutHintPaneTabYOffset 0.0)" 1)" -shortcutHintAlwaysShow="$(read_value shortcutHintAlwaysShow 0)" - -bgGlassEnabled="$(read_value bgGlassEnabled 1)" -bgGlassMaterial="$(read_value bgGlassMaterial hudWindow)" -bgGlassTintHex="$(read_value bgGlassTintHex '#000000')" -bgGlassTintOpacity="$(format_number "$(read_value bgGlassTintOpacity 0.05)" 2)" - -menubarDebugPreviewEnabled="$(read_value menubarDebugPreviewEnabled 0)" -menubarDebugPreviewCount="$(read_value menubarDebugPreviewCount 1)" -menubarDebugBadgeRectX="$(format_number "$(read_value menubarDebugBadgeRectX 5.38)" 2)" -menubarDebugBadgeRectY="$(format_number "$(read_value menubarDebugBadgeRectY 6.43)" 2)" -menubarDebugBadgeRectWidth="$(format_number "$(read_value menubarDebugBadgeRectWidth 10.75)" 2)" -menubarDebugBadgeRectHeight="$(format_number "$(read_value menubarDebugBadgeRectHeight 11.58)" 2)" -menubarDebugSingleDigitFontSize="$(format_number "$(read_value menubarDebugSingleDigitFontSize 6.70)" 2)" -menubarDebugMultiDigitFontSize="$(format_number "$(read_value menubarDebugMultiDigitFontSize 6.70)" 2)" -menubarDebugSingleDigitYOffset="$(format_number "$(read_value menubarDebugSingleDigitYOffset 0.60)" 2)" -menubarDebugMultiDigitYOffset="$(format_number "$(read_value menubarDebugMultiDigitYOffset 0.60)" 2)" -legacySingleDigitX="$(read_value menubarDebugTextRectXAdjust '')" -if [[ -n "$legacySingleDigitX" ]]; then -menubarDebugSingleDigitXAdjust="$(format_number "$legacySingleDigitX" 2)" -else - menubarDebugSingleDigitXAdjust="$(format_number "$(read_value menubarDebugSingleDigitXAdjust -1.10)" 2)" -fi -menubarDebugMultiDigitXAdjust="$(format_number "$(read_value menubarDebugMultiDigitXAdjust 2.42)" 2)" -menubarDebugTextRectWidthAdjust="$(format_number "$(read_value menubarDebugTextRectWidthAdjust 1.80)" 2)" - -browserDevToolsIconName="$(read_value browserDevToolsIconName 'wrench.and.screwdriver')" -browserDevToolsIconColor="$(read_value browserDevToolsIconColor bonsplitInactive)" - -payload="$(cat </dev/null 2>&1; then - printf '%s' "$payload" | pbcopy - echo "Copied debug snapshot to clipboard." - else - echo "pbcopy not available; skipped clipboard copy." >&2 - fi -fi diff --git a/skills/cmux-diagnostics/SKILL.md b/skills/cmux-diagnostics/SKILL.md new file mode 100644 index 000000000000..0580d918cff2 --- /dev/null +++ b/skills/cmux-diagnostics/SKILL.md @@ -0,0 +1,84 @@ +--- +name: cmux-diagnostics +description: "Run end-user cmux diagnostics. Use when cmux hooks, notifications, session restore, settings, browser automation, socket access, CLI control, or agent resume behavior is not working, or when the user asks for a cmux health check, doctor report, or support-safe debug summary." +--- + +# cmux Diagnostics + +Use this skill to collect and interpret support-safe cmux diagnostics for end users. Default to read-only checks. Do not dump hook config files, session stores, prompt logs, tokens, or environment secrets. + +## Quick Report + +Run the bundled read-only diagnostic script first: + +```bash +# From a cmux checkout +skills/cmux-diagnostics/scripts/cmux-diagnostics + +# From an installed skill +~/.agents/skills/cmux-diagnostics/scripts/cmux-diagnostics + +# From a Codex-only skills.sh install +~/.codex/skills/cmux-diagnostics/scripts/cmux-diagnostics +``` + +Use `--include-context` only when workspace names, cwd paths, and current cmux identifiers are relevant to the user-reported issue: + +```bash +skills/cmux-diagnostics/scripts/cmux-diagnostics --include-context +``` + +## What to Check + +1. CLI and socket health: + ```bash + command -v cmux + cmux ping + cmux capabilities --json + ``` + If socket commands fail, check whether the agent is running inside a cmux terminal and whether socket automation is enabled. + +2. Settings health: + ```bash + ~/.agents/skills/cmux-settings/scripts/cmux-settings validate + ~/.agents/skills/cmux-settings/scripts/cmux-settings get terminal.autoResumeAgentSessions + ``` + If the user installed with `skills.sh`, use `~/.codex/skills/cmux-settings/scripts/cmux-settings` instead. + If `terminal.autoResumeAgentSessions` is false, cmux restores panes but will not automatically resume saved agent sessions. + +3. Hook installation: + ```bash + cmux hooks setup --agent codex + cmux hooks setup --agent opencode + cmux hooks setup + ``` + Only run install or uninstall commands after the user agrees. `cmux hooks setup` installs supported agents found on PATH and skips missing agents. + +4. Session restore evidence: + ```bash + ls -lh ~/.cmuxterm/*-hook-sessions.json 2>/dev/null + ``` + Missing session stores usually means the agent has not run inside cmux since hooks were installed, hooks are disabled, or the agent integration does not support resume capture. + +5. Notification path: + ```bash + cmux notify "cmux diagnostic test" + ``` + Use this only when the user is ready for a visible test notification. + +## Interpretation + +- `cmux` not found: the CLI is not installed or not on PATH for this shell. +- `cmux ping` fails: app is not reachable through the current socket path, the app is closed, or automation access is disabled. +- No `CMUX_WORKSPACE_ID` or `CMUX_SURFACE_ID`: the command is probably running outside a cmux terminal. Some hooks intentionally no-op outside cmux. +- Hook config exists but no session store: run one supported agent inside cmux after installing hooks, then re-check. +- Session store exists but restore does not launch agents: check `terminal.autoResumeAgentSessions` and whether the saved executable still exists on PATH. +- Settings validation fails: fix the config first. Invalid config can make later symptoms misleading. + +## Rules + +- Stay read-only until the user asks to fix something. +- Never print raw hook files, session JSON, prompt logs, shell history, tokens, or API keys. +- Summarize file presence, size, modified time, and marker presence instead of contents. +- Prefer narrow fixes such as `cmux hooks setup --agent codex` over reinstalling every integration. +- After a fix, rerun the diagnostic script and report the changed lines. diff --git a/skills/cmux-diagnostics/agents/openai.yaml b/skills/cmux-diagnostics/agents/openai.yaml new file mode 100644 index 000000000000..364b6e193551 --- /dev/null +++ b/skills/cmux-diagnostics/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "cmux Diagnostics" + short_description: "Check cmux hooks, restore, CLI, and settings." + default_prompt: "Use $cmux-diagnostics to collect a read-only cmux health report and explain any hook or session restore problems." diff --git a/skills/cmux-diagnostics/scripts/cmux-diagnostics b/skills/cmux-diagnostics/scripts/cmux-diagnostics new file mode 100755 index 000000000000..ffe29f6adfd6 --- /dev/null +++ b/skills/cmux-diagnostics/scripts/cmux-diagnostics @@ -0,0 +1,180 @@ +#!/usr/bin/env bash +set -euo pipefail + +include_context=0 +while [[ $# -gt 0 ]]; do + case "$1" in + --include-context) + include_context=1 + shift + ;; + -h|--help) + cat <<'EOF' +Usage: cmux-diagnostics [--include-context] + +Print a read-only, support-safe cmux diagnostics report. By default this avoids +workspace names, cwd paths, hook contents, session JSON, and secrets. +EOF + exit 0 + ;; + *) + printf 'cmux-diagnostics: unknown option: %s\n' "$1" >&2 + exit 1 + ;; + esac +done + +section() { + printf '\n== %s ==\n' "$1" +} + +safe_path() { + local path="$1" + if [[ "$path" == "$HOME" ]]; then + printf '~' + elif [[ "$path" == "$HOME"/* ]]; then + printf '~/%s' "${path#"$HOME"/}" + else + printf '%s' "$path" + fi +} + +run_status() { + local label="$1" + shift + printf '%s: ' "$label" + if "$@" >/dev/null 2>&1; then + printf 'ok\n' + else + printf 'failed\n' + fi +} + +file_summary() { + local path="$1" + if [[ -e "$path" ]]; then + local bytes modified + bytes="$(wc -c <"$path" 2>/dev/null | tr -d ' ' || true)" + modified="$(stat -f '%Sm' -t '%Y-%m-%d %H:%M:%S %z' "$path" 2>/dev/null || stat -c '%y' "$path" 2>/dev/null || printf 'unknown')" + printf 'present bytes=%s modified=%s\n' "${bytes:-unknown}" "$modified" + else + printf 'missing\n' + fi +} + +marker_summary() { + local path="$1" + local marker="$2" + if [[ -e "$path" ]]; then + if grep -Fq "$marker" "$path" 2>/dev/null; then + printf 'marker-present\n' + else + printf 'marker-missing\n' + fi + else + printf 'missing\n' + fi +} + +script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)" +skill_dir="$(cd -- "$script_dir/.." >/dev/null 2>&1 && pwd)" +skills_root="$(cd -- "$skill_dir/.." >/dev/null 2>&1 && pwd)" +settings_helper="$skills_root/cmux-settings/scripts/cmux-settings" +if [[ ! -x "$settings_helper" && -x "$HOME/.codex/skills/cmux-settings/scripts/cmux-settings" ]]; then + settings_helper="$HOME/.codex/skills/cmux-settings/scripts/cmux-settings" +fi + +section "cmux diagnostics" +printf 'date: %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" +printf 'shell: %s\n' "${SHELL:-unknown}" +printf 'inside_cmux: ' +if [[ -n "${CMUX_WORKSPACE_ID:-}" || -n "${CMUX_SURFACE_ID:-}" ]]; then + printf 'yes\n' +else + printf 'no\n' +fi +printf 'cmux_workspace_id_set: %s\n' "$([[ -n "${CMUX_WORKSPACE_ID:-}" ]] && printf yes || printf no)" +printf 'cmux_surface_id_set: %s\n' "$([[ -n "${CMUX_SURFACE_ID:-}" ]] && printf yes || printf no)" +socket_path="${CMUX_SOCKET_PATH:-${CMUX_SOCKET:-unset}}" +if [[ "$socket_path" == "unset" ]]; then + printf 'cmux_socket_path: unset\n' +else + printf 'cmux_socket_path: %s\n' "$(safe_path "$socket_path")" +fi +printf 'cmux_socket_password_set: %s\n' "$([[ -n "${CMUX_SOCKET_PASSWORD:-}" ]] && printf yes || printf no)" + +section "cli" +if command -v cmux >/dev/null 2>&1; then + printf 'cmux_path: %s\n' "$(safe_path "$(command -v cmux)")" + if cmux --version >/dev/null 2>&1; then + printf 'cmux_version: %s\n' "$(cmux --version 2>/dev/null | head -n 1)" + else + printf 'cmux_version: unavailable\n' + fi + run_status "cmux_ping" cmux ping + run_status "cmux_capabilities" cmux capabilities --json + if [[ "$include_context" -eq 1 ]]; then + printf 'identify_json:\n' + cmux identify --json 2>/dev/null || printf ' unavailable\n' + fi +else + printf 'cmux_path: missing\n' +fi + +section "settings" +printf 'cmux_json: ' +file_summary "$HOME/.config/cmux/cmux.json" +printf 'legacy_settings_json: ' +file_summary "$HOME/.config/cmux/settings.json" +if [[ -x "$settings_helper" ]]; then + run_status "cmux_settings_validate" "$settings_helper" validate + printf 'auto_resume_agent_sessions: ' + "$settings_helper" get terminal.autoResumeAgentSessions 2>/dev/null || printf 'default-or-unset\n' +else + printf 'cmux_settings_helper: missing (%s)\n' "$(safe_path "$settings_helper")" +fi + +section "hook configs" +declare -a hook_checks=( + "codex:$HOME/.codex/hooks.json:cmux hooks codex" + "codex-config:$HOME/.codex/config.toml:codex_hooks" + "opencode-session:$HOME/.config/opencode/plugins/cmux-session.js:cmux hooks opencode" + "opencode-feed:$HOME/.config/opencode/plugins/cmux-feed.js:cmux hooks feed --source opencode" + "pi:$HOME/.pi/agent/extensions/cmux-session.ts:cmux hooks pi" + "amp:$HOME/.config/amp/plugins/cmux-session.ts:cmux hooks amp" + "cursor:$HOME/.cursor/hooks.json:cmux hooks cursor" + "gemini:$HOME/.gemini/settings.json:cmux hooks gemini" + "rovodev:$HOME/.rovodev/rovodev.yml:cmux hooks rovodev" + "hermes-agent:$HOME/.hermes/config.yaml:cmux hooks hermes-agent" + "copilot:$HOME/.copilot/settings.json:cmux hooks copilot" + "codebuddy:$HOME/.codebuddy/settings.json:cmux hooks codebuddy" + "factory:$HOME/.factory/settings.json:cmux hooks factory" + "qoder:$HOME/.qoder/settings.json:cmux hooks qoder" +) +for entry in "${hook_checks[@]}"; do + IFS=: read -r name path marker <<<"$entry" + printf '%s: %s ' "$name" "$(safe_path "$path")" + marker_summary "$path" "$marker" +done + +section "session stores" +shopt -s nullglob +stores=("$HOME"/.cmuxterm/*-hook-sessions.json) +if [[ "${#stores[@]}" -eq 0 ]]; then + printf 'session_store_files: none\n' +else + printf 'session_store_files: %s\n' "${#stores[@]}" + for path in "${stores[@]}"; do + printf '%s: ' "$(basename "$path")" + file_summary "$path" + done +fi + +section "agent binaries" +for bin in claude codex opencode pi amp cursor-agent gemini rovo rovodev hermes-agent gh copilot codebuddy droid qodercli; do + if command -v "$bin" >/dev/null 2>&1; then + printf '%s: present (%s)\n' "$bin" "$(safe_path "$(command -v "$bin")")" + else + printf '%s: missing\n' "$bin" + fi +done diff --git a/web/app/[locale]/docs/skills/page.tsx b/web/app/[locale]/docs/skills/page.tsx index 5e8718fad995..01ccb5b06238 100644 --- a/web/app/[locale]/docs/skills/page.tsx +++ b/web/app/[locale]/docs/skills/page.tsx @@ -31,6 +31,22 @@ const skills = [ descriptionKey: "settingsDescription", useKey: "settingsUse", }, + { + id: "cmux-customization", + path: "skills/cmux-customization/SKILL.md", + command: "cmux reload-config", + nameKey: "customizationName", + descriptionKey: "customizationDescription", + useKey: "customizationUse", + }, + { + id: "cmux-diagnostics", + path: "skills/cmux-diagnostics/SKILL.md", + command: "skills/cmux-diagnostics/scripts/cmux-diagnostics", + nameKey: "diagnosticsName", + descriptionKey: "diagnosticsDescription", + useKey: "diagnosticsUse", + }, { id: "cmux-browser", path: "skills/cmux-browser/SKILL.md", @@ -47,14 +63,6 @@ const skills = [ descriptionKey: "markdownDescription", useKey: "markdownUse", }, - { - id: "cmux-debug-windows", - path: "skills/cmux-debug-windows/SKILL.md", - command: "skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh", - nameKey: "debugWindowsName", - descriptionKey: "debugWindowsDescription", - useKey: "debugWindowsUse", - }, ] as const; const skillCoverage = [ @@ -76,6 +84,18 @@ const skillCoverage = [ scopeKey: "settingsScope", referencesKey: "settingsReferences", }, + { + id: "cmux-customization", + nameKey: "customizationName", + scopeKey: "customizationScope", + referencesKey: "customizationReferences", + }, + { + id: "cmux-diagnostics", + nameKey: "diagnosticsName", + scopeKey: "diagnosticsScope", + referencesKey: "diagnosticsReferences", + }, { id: "cmux-browser", nameKey: "browserName", @@ -88,33 +108,9 @@ const skillCoverage = [ scopeKey: "markdownScope", referencesKey: "markdownReferences", }, - { - id: "cmux-debug-windows", - nameKey: "debugWindowsName", - scopeKey: "debugWindowsScope", - referencesKey: "debugWindowsReferences", - }, ] as const; const suggestedSkills = [ - { - id: "cmux-custom-commands", - nameKey: "suggestCustomCommandsName", - useKey: "suggestCustomCommandsUse", - whyKey: "suggestCustomCommandsWhy", - }, - { - id: "cmux-agent-hooks", - nameKey: "suggestAgentHooksName", - useKey: "suggestAgentHooksUse", - whyKey: "suggestAgentHooksWhy", - }, - { - id: "cmux-notifications", - nameKey: "suggestNotificationsName", - useKey: "suggestNotificationsUse", - whyKey: "suggestNotificationsWhy", - }, { id: "cmux-ssh", nameKey: "suggestSshName", @@ -163,7 +159,9 @@ export default function SkillsPage() { code: (chunks) => {chunks}, })}

- {`curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/skills.sh | bash`} + {`npx skills add manaflow-ai/cmux --all -g -y +npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -y`} + {`curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/skills.sh | bash`} {t.rich("installDestination", { code: (chunks) => {chunks}, diff --git a/web/messages/en.json b/web/messages/en.json index d04fb1bb11f8..b1f7cf31c9e2 100644 --- a/web/messages/en.json +++ b/web/messages/en.json @@ -782,12 +782,13 @@ "skills": { "title": "Skills", "metaTitle": "Skills", - "metaDescription": "Install and use cmux agent skills for core CLI control, workspace automation, settings, browser automation, markdown panels, and debug windows.", - "intro": "cmux ships skills that teach coding agents how to use cmux CLI control, current-workspace automation, settings, browser surfaces, markdown panels, and debug windows.", + "metaDescription": "Install and use cmux agent skills for core CLI control, workspace automation, settings, customization, diagnostics, browser automation, and markdown panels.", + "intro": "cmux ships skills that teach coding agents how to use cmux CLI control, current-workspace automation, settings, customization, diagnostics, browser surfaces, and markdown panels.", "installTitle": "Install", - "installIntro": "Run skills.sh to install the checked-in skills into your Codex skills directory.", - "installFromGitHub": "Install from GitHub", - "installDestination": "By default, the script installs into ~/.codex/skills, or $CODEX_HOME/skills when CODEX_HOME is set. Pass --dest when your agent reads skills from another directory.", + "installIntro": "Use Vercel's skills CLI for the standard multi-agent install flow, or use skills.sh when you only need the Codex skills directory.", + "installWithVercel": "Install with Vercel skills", + "installWithSkillsSh": "Install with skills.sh", + "installDestination": "By default, skills.sh installs into ~/.codex/skills, or $CODEX_HOME/skills when CODEX_HOME is set. Pass --dest when your agent reads skills from another directory.", "localInstallTitle": "Install from a checkout", "localInstallIntro": "From a cloned cmux checkout, the script uses the local skills directory.", "localInstallCommands": "Local commands", @@ -806,15 +807,18 @@ "settingsName": "cmux Settings", "settingsDescription": "Inspects, edits, validates, and opens ~/.config/cmux/cmux.json with a bundled helper script.", "settingsUse": "Use it when changing appearance, sidebar, notification, browser, automation, or shortcut settings by JSON path.", + "customizationName": "cmux Customization", + "customizationDescription": "Customizes cmux.json actions, workspace layouts, toolbar buttons, Command Palette entries, shortcuts, and Ghostty-owned terminal preferences.", + "customizationUse": "Use it for multi-part workflow customization that spans actions, layouts, shortcuts, or app preferences.", + "diagnosticsName": "cmux Diagnostics", + "diagnosticsDescription": "Runs support-safe checks for cmux CLI health, socket access, hooks, session restore, settings, and agent binaries.", + "diagnosticsUse": "Use it when notifications, hooks, restore, or automation are not behaving as expected.", "browserName": "cmux Browser", "browserDescription": "Automates cmux webview surfaces with snapshot refs, DOM actions, waits, screenshots, and session state.", "browserUse": "Use it for browser tasks that should run inside cmux instead of a separate browser automation tool.", "markdownName": "cmux Markdown Viewer", "markdownDescription": "Opens markdown files in a formatted cmux panel with live reload.", "markdownUse": "Use it to show plans, docs, notes, and task lists beside the terminal while work is happening.", - "debugWindowsName": "cmux Debug Windows", - "debugWindowsDescription": "Manages Sidebar Debug, Background Debug, Menu Bar Extra Debug, and copyable debug snapshots.", - "debugWindowsUse": "Use it when iterating on debug window UI or collecting debug configuration from a tagged build.", "coverageTitle": "What the skills cover", "coverageIntro": "The top-level SKILL.md files stay short. Deeper command details live in references, scripts, and templates next to each skill.", "scopeHeader": "Scope", @@ -825,12 +829,14 @@ "workspaceReferences": "Workspace command reference covering context, windows, workspaces, panes, surfaces, input, sidebar state, notifications, docs, and tagged reloads.", "settingsScope": "cmux.json settings reads and writes, key lookup, JSONC parsing, safe atomic updates, validation, editor opening, and shortcut binding edits.", "settingsReferences": "Generated settings key list, shortcut action ids, schema URL, supported path detection, and the bundled cmux-settings helper.", + "customizationScope": "End-user customization across cmux.json settings, actions, commands, workspace layouts, toolbar buttons, Command Palette entries, shortcuts, and Ghostty config boundaries.", + "customizationReferences": "Config-surface selection, global versus project-local scope, action examples, workspace layout examples, reload steps, validation rules, and safety constraints.", + "diagnosticsScope": "Read-only health checks for CLI reachability, socket access, cmux environment, settings validation, hook installation markers, session stores, auto-resume settings, and supported agent binaries.", + "diagnosticsReferences": "Bundled support-safe diagnostic script, hook setup commands, session restore interpretation, notification checks, and rules for redacting sensitive files.", "browserScope": "Browser automation inside cmux webview surfaces, including navigation, DOM actions, waits, state capture, screenshots, and snapshots.", "browserReferences": "Command mapping, snapshot ref lifecycle, authentication, session persistence, video status, proxy behavior, and reusable automation templates.", "markdownScope": "Formatted markdown panels that live beside terminals and reload as files change.", "markdownReferences": "Command syntax, routing options, live reload behavior, atomic file replacement, and markdown rendering coverage.", - "debugWindowsScope": "Debug menu wiring and debug window state capture for tagged development builds.", - "debugWindowsReferences": "Debug window menu entries, copyable per-window configs, combined snapshot capture, bundle targeting, and the snapshot helper script.", "helpMenuTitle": "Help menu", "helpMenuIntro": "The macOS Help menu mirrors this docs sidebar and includes Skills. Use the Skills item in Help to open this page from the app.", "authoringTitle": "Skill layout", @@ -841,15 +847,6 @@ "suggestionHeader": "Skill idea", "suggestionUseHeader": "Use case", "suggestionWhyHeader": "Why it helps", - "suggestCustomCommandsName": "cmux Custom Commands", - "suggestCustomCommandsUse": "Author cmux.json actions, workspace commands, toolbar buttons, command palette entries, icons, and confirmation prompts.", - "suggestCustomCommandsWhy": "Custom commands are powerful enough that agents need a schema-aware workflow instead of editing large JSON blocks by hand.", - "suggestAgentHooksName": "cmux Agent Hooks", - "suggestAgentHooksUse": "Configure Claude Code, Codex, OpenCode, Rovo Dev, and generic notification hooks so agent status reaches cmux reliably.", - "suggestAgentHooksWhy": "Hook setup differs by agent, and a skill could keep install, verify, and troubleshoot steps consistent.", - "suggestNotificationsName": "cmux Notifications", - "suggestNotificationsUse": "Tune notification sounds, dock badges, unread rings, pane flash, hooks, and sidebar notification behavior.", - "suggestNotificationsWhy": "Notifications span UI settings, shell hooks, CLI notify commands, and sidebar state.", "suggestSshName": "cmux SSH", "suggestSshUse": "Drive remote workspaces, SSH URL launches, browser routing through remote networks, and reconnect behavior.", "suggestSshWhy": "Remote sessions are a major cmux surface with behavior that differs from local terminal workflows.", diff --git a/web/messages/ja.json b/web/messages/ja.json index 3ee10b42f1f5..805f1ebcac8a 100644 --- a/web/messages/ja.json +++ b/web/messages/ja.json @@ -675,12 +675,13 @@ "skills": { "title": "スキル", "metaTitle": "スキル", - "metaDescription": "cmux のエージェントスキルをインストールして、CLI 制御、workspace 自動化、settings、ブラウザ自動化、Markdown パネル、デバッグウィンドウに使えます。", - "intro": "cmux には、コーディングエージェントに cmux CLI 制御、current workspace 自動化、settings、ブラウザサーフェス、Markdown パネル、デバッグウィンドウの使い方を教えるスキルが含まれています。", + "metaDescription": "cmux のエージェントスキルをインストールして、CLI 制御、workspace 自動化、settings、customization、diagnostics、ブラウザ自動化、Markdown パネルに使えます。", + "intro": "cmux には、コーディングエージェントに cmux CLI 制御、current workspace 自動化、settings、customization、diagnostics、ブラウザサーフェス、Markdown パネルの使い方を教えるスキルが含まれています。", "installTitle": "インストール", - "installIntro": "skills.sh を実行すると、リポジトリ内のスキルを Codex のスキルディレクトリへインストールできます。", - "installFromGitHub": "GitHub からインストール", - "installDestination": "デフォルトでは、スクリプトは ~/.codex/skills にインストールします。CODEX_HOME が設定されている場合は $CODEX_HOME/skills にインストールします。エージェントが別のディレクトリからスキルを読む場合は --dest を渡してください。", + "installIntro": "標準の複数エージェント向けインストールには Vercel の skills CLI を使います。Codex の skills ディレクトリだけでよい場合は skills.sh も使えます。", + "installWithVercel": "Vercel skills でインストール", + "installWithSkillsSh": "skills.sh でインストール", + "installDestination": "デフォルトでは、skills.sh は ~/.codex/skills にインストールします。CODEX_HOME が設定されている場合は $CODEX_HOME/skills にインストールします。エージェントが別のディレクトリからスキルを読む場合は --dest を渡してください。", "localInstallTitle": "チェックアウトからインストール", "localInstallIntro": "クローン済みの cmux チェックアウトでは、スクリプトはローカルの skills ディレクトリを使います。", "localInstallCommands": "ローカルコマンド", @@ -699,15 +700,18 @@ "settingsName": "cmux Settings", "settingsDescription": "同梱 helper script で ~/.config/cmux/cmux.json を確認、編集、検証、open します。", "settingsUse": "appearance、sidebar、notification、browser、automation、shortcut の設定を JSON path で変更するときに使います。", + "customizationName": "cmux Customization", + "customizationDescription": "cmux.json の action、workspace layout、toolbar button、Command Palette entry、shortcut、Ghostty が扱う terminal preference を調整します。", + "customizationUse": "単一の設定変更だけでなく、ユーザーの workflow に合わせて cmux の挙動を調整するときに使います。", + "diagnosticsName": "cmux Diagnostics", + "diagnosticsDescription": "cmux CLI、socket access、hook、session restore、settings、agent binary を、support-safe に確認します。", + "diagnosticsUse": "notification、hook、restore、automation が期待どおり動かないときに使います。", "browserName": "cmux Browser", "browserDescription": "snapshot 参照、DOM 操作、待機、スクリーンショット、セッション状態を使って cmux の webview サーフェスを自動化します。", "browserUse": "別のブラウザ自動化ツールではなく、cmux 内で実行すべきブラウザタスクに使います。", "markdownName": "cmux Markdown Viewer", "markdownDescription": "Markdown ファイルを、ライブリロード付きの整形された cmux パネルで開きます。", "markdownUse": "作業中に計画、ドキュメント、メモ、タスクリストをターミナルの横に表示するときに使います。", - "debugWindowsName": "cmux Debug Windows", - "debugWindowsDescription": "Sidebar Debug、Background Debug、Menu Bar Extra Debug、コピー可能なデバッグ snapshot を管理します。", - "debugWindowsUse": "デバッグウィンドウ UI を調整するときや、タグ付きビルドからデバッグ設定を収集するときに使います。", "coverageTitle": "スキルが扱う範囲", "coverageIntro": "トップレベルの SKILL.md は短く保ちます。詳しいコマンド情報は、各スキルの横にある references、scripts、templates に置きます。", "scopeHeader": "範囲", @@ -718,12 +722,14 @@ "workspaceReferences": "context、window、workspace、pane、surface、input、sidebar state、notification、docs、tagged reload を扱う workspace command reference です。", "settingsScope": "cmux.json の読み書き、key lookup、JSONC parsing、安全な atomic update、validation、editor open、shortcut binding 編集です。", "settingsReferences": "生成済み settings key list、shortcut action id、schema URL、supported path 検出、同梱 cmux-settings helper です。", + "customizationScope": "cmux.json settings、action、command、workspace layout、toolbar button、Command Palette entry、shortcut、Ghostty config との境界をまたぐ end-user customization です。", + "customizationReferences": "設定面の選択、global と project-local の使い分け、action 例、workspace layout 例、reload 手順、validation rule、安全制約です。", + "diagnosticsScope": "CLI 到達性、socket access、cmux environment、settings validation、hook installation marker、session store、auto-resume setting、対応 agent binary の read-only health check です。", + "diagnosticsReferences": "同梱の support-safe diagnostic script、hook setup command、session restore の解釈、notification check、機密ファイルを伏せるルールです。", "browserScope": "cmux の webview サーフェス内でのブラウザ自動化です。ナビゲーション、DOM 操作、待機、状態取得、スクリーンショット、snapshot を扱います。", "browserReferences": "コマンド対応表、snapshot 参照のライフサイクル、認証、セッション永続化、動画の現状、プロキシ動作、再利用可能な自動化テンプレートです。", "markdownScope": "ターミナルの横に置けて、ファイル変更に合わせて再読み込みされる整形済み Markdown パネルです。", "markdownReferences": "コマンド構文、ルーティングオプション、ライブリロード動作、atomic なファイル置換、Markdown レンダリング範囲です。", - "debugWindowsScope": "タグ付き開発ビルド向けの Debug メニュー配線とデバッグウィンドウ状態の取得です。", - "debugWindowsReferences": "デバッグウィンドウのメニュー項目、各ウィンドウのコピー可能な設定、統合 snapshot 取得、bundle 指定、snapshot 補助スクリプトです。", "helpMenuTitle": "ヘルプメニュー", "helpMenuIntro": "macOS の Help メニューはこのドキュメントサイドバーに合わせており、Skills も含みます。アプリからこのページを開くには、Help の Skills 項目を使います。", "authoringTitle": "スキルの構成", @@ -734,15 +740,6 @@ "suggestionHeader": "スキル案", "suggestionUseHeader": "用途", "suggestionWhyHeader": "有用な理由", - "suggestCustomCommandsName": "cmux Custom Commands", - "suggestCustomCommandsUse": "cmux.json の action、workspace command、toolbar button、command palette entry、icon、confirmation prompt を作成します。", - "suggestCustomCommandsWhy": "Custom command は強力なので、agent には大きな JSON block を手編集するより schema-aware な workflow が必要です。", - "suggestAgentHooksName": "cmux Agent Hooks", - "suggestAgentHooksUse": "Claude Code、Codex、OpenCode、Rovo Dev、generic notification hook を設定し、agent status を cmux に安定して届けます。", - "suggestAgentHooksWhy": "Hook setup は agent ごとに違うため、install、verify、troubleshoot の手順を skill にまとめられます。", - "suggestNotificationsName": "cmux Notifications", - "suggestNotificationsUse": "notification sound、dock badge、unread ring、pane flash、hook、sidebar notification behavior を調整します。", - "suggestNotificationsWhy": "Notification は UI settings、shell hook、CLI notify command、sidebar state にまたがります。", "suggestSshName": "cmux SSH", "suggestSshUse": "リモートワークスペース、SSH URL 起動、リモートネットワーク経由のブラウザルーティング、再接続動作を扱います。", "suggestSshWhy": "リモートセッションは cmux の主要な surface で、ローカル terminal workflow と異なる挙動があります。", From d579ec7199f237d2983e5770e5704c28b76c2de0 Mon Sep 17 00:00:00 2001 From: Lawrence Chen Date: Fri, 15 May 2026 17:05:05 -0700 Subject: [PATCH 2/4] Address skills review feedback --- skills/cmux-customization/SKILL.md | 6 ++++++ skills/cmux-diagnostics/SKILL.md | 10 ++++++++++ skills/cmux-diagnostics/scripts/cmux-diagnostics | 4 +++- web/app/[locale]/docs/skills/page.tsx | 5 ++++- 4 files changed, 23 insertions(+), 2 deletions(-) diff --git a/skills/cmux-customization/SKILL.md b/skills/cmux-customization/SKILL.md index 0e0c4946a0ad..d2410d3fd92d 100644 --- a/skills/cmux-customization/SKILL.md +++ b/skills/cmux-customization/SKILL.md @@ -19,23 +19,29 @@ If a request can be handled by Ghostty config, say that and use Ghostty config i ## 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. ## Common Patterns diff --git a/skills/cmux-diagnostics/SKILL.md b/skills/cmux-diagnostics/SKILL.md index 0580d918cff2..1d892ea86bb9 100644 --- a/skills/cmux-diagnostics/SKILL.md +++ b/skills/cmux-diagnostics/SKILL.md @@ -31,39 +31,49 @@ skills/cmux-diagnostics/scripts/cmux-diagnostics --include-context ## What to Check 1. CLI and socket health: + ```bash command -v cmux cmux ping cmux capabilities --json ``` + If socket commands fail, check whether the agent is running inside a cmux terminal and whether socket automation is enabled. 2. Settings health: + ```bash ~/.agents/skills/cmux-settings/scripts/cmux-settings validate ~/.agents/skills/cmux-settings/scripts/cmux-settings get terminal.autoResumeAgentSessions ``` + If the user installed with `skills.sh`, use `~/.codex/skills/cmux-settings/scripts/cmux-settings` instead. If `terminal.autoResumeAgentSessions` is false, cmux restores panes but will not automatically resume saved agent sessions. 3. Hook installation: + ```bash cmux hooks setup --agent codex cmux hooks setup --agent opencode cmux hooks setup ``` + Only run install or uninstall commands after the user agrees. `cmux hooks setup` installs supported agents found on PATH and skips missing agents. 4. Session restore evidence: + ```bash ls -lh ~/.cmuxterm/*-hook-sessions.json 2>/dev/null ``` + Missing session stores usually means the agent has not run inside cmux since hooks were installed, hooks are disabled, or the agent integration does not support resume capture. 5. Notification path: + ```bash cmux notify "cmux diagnostic test" ``` + Use this only when the user is ready for a visible test notification. ## Interpretation diff --git a/skills/cmux-diagnostics/scripts/cmux-diagnostics b/skills/cmux-diagnostics/scripts/cmux-diagnostics index ffe29f6adfd6..036abdbc583e 100755 --- a/skills/cmux-diagnostics/scripts/cmux-diagnostics +++ b/skills/cmux-diagnostics/scripts/cmux-diagnostics @@ -80,7 +80,9 @@ script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)" skill_dir="$(cd -- "$script_dir/.." >/dev/null 2>&1 && pwd)" skills_root="$(cd -- "$skill_dir/.." >/dev/null 2>&1 && pwd)" settings_helper="$skills_root/cmux-settings/scripts/cmux-settings" -if [[ ! -x "$settings_helper" && -x "$HOME/.codex/skills/cmux-settings/scripts/cmux-settings" ]]; then +if [[ ! -x "$settings_helper" && -x "$HOME/.agents/skills/cmux-settings/scripts/cmux-settings" ]]; then + settings_helper="$HOME/.agents/skills/cmux-settings/scripts/cmux-settings" +elif [[ ! -x "$settings_helper" && -x "$HOME/.codex/skills/cmux-settings/scripts/cmux-settings" ]]; then settings_helper="$HOME/.codex/skills/cmux-settings/scripts/cmux-settings" fi diff --git a/web/app/[locale]/docs/skills/page.tsx b/web/app/[locale]/docs/skills/page.tsx index 01ccb5b06238..5902d71a0d04 100644 --- a/web/app/[locale]/docs/skills/page.tsx +++ b/web/app/[locale]/docs/skills/page.tsx @@ -159,7 +159,10 @@ export default function SkillsPage() { code: (chunks) => {chunks}, })}

- {`npx skills add manaflow-ai/cmux --all -g -y + {`# Install all cmux skills +npx skills add manaflow-ai/cmux --all -g -y + +# Or install just diagnostics npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -y`} {`curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/skills.sh | bash`} From 37c2a98f204aff67b518bbdbae8e97ddb7c395d2 Mon Sep 17 00:00:00 2001 From: Lawrence Chen Date: Fri, 15 May 2026 17:12:39 -0700 Subject: [PATCH 3/4] Avoid socket path sentinel in diagnostics --- skills/cmux-diagnostics/scripts/cmux-diagnostics | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/skills/cmux-diagnostics/scripts/cmux-diagnostics b/skills/cmux-diagnostics/scripts/cmux-diagnostics index 036abdbc583e..10a6089b051c 100755 --- a/skills/cmux-diagnostics/scripts/cmux-diagnostics +++ b/skills/cmux-diagnostics/scripts/cmux-diagnostics @@ -97,11 +97,12 @@ else fi printf 'cmux_workspace_id_set: %s\n' "$([[ -n "${CMUX_WORKSPACE_ID:-}" ]] && printf yes || printf no)" printf 'cmux_surface_id_set: %s\n' "$([[ -n "${CMUX_SURFACE_ID:-}" ]] && printf yes || printf no)" -socket_path="${CMUX_SOCKET_PATH:-${CMUX_SOCKET:-unset}}" -if [[ "$socket_path" == "unset" ]]; then - printf 'cmux_socket_path: unset\n' +if [[ "${CMUX_SOCKET_PATH+x}" == "x" ]]; then + printf 'cmux_socket_path: %s (from CMUX_SOCKET_PATH)\n' "$(safe_path "$CMUX_SOCKET_PATH")" +elif [[ "${CMUX_SOCKET+x}" == "x" ]]; then + printf 'cmux_socket_path: %s (from CMUX_SOCKET)\n' "$(safe_path "$CMUX_SOCKET")" else - printf 'cmux_socket_path: %s\n' "$(safe_path "$socket_path")" + printf 'cmux_socket_path: unset\n' fi printf 'cmux_socket_password_set: %s\n' "$([[ -n "${CMUX_SOCKET_PASSWORD:-}" ]] && printf yes || printf no)" From b8be11009d0d59a8d014eefb4da5881fd6d53b0f Mon Sep 17 00:00:00 2001 From: Lawrence Chen Date: Fri, 15 May 2026 17:26:59 -0700 Subject: [PATCH 4/4] Guard diagnostics against special files --- skills/cmux-diagnostics/scripts/cmux-diagnostics | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/skills/cmux-diagnostics/scripts/cmux-diagnostics b/skills/cmux-diagnostics/scripts/cmux-diagnostics index 10a6089b051c..623374247b0c 100755 --- a/skills/cmux-diagnostics/scripts/cmux-diagnostics +++ b/skills/cmux-diagnostics/scripts/cmux-diagnostics @@ -52,11 +52,13 @@ run_status() { file_summary() { local path="$1" - if [[ -e "$path" ]]; then + if [[ -f "$path" ]]; then local bytes modified bytes="$(wc -c <"$path" 2>/dev/null | tr -d ' ' || true)" modified="$(stat -f '%Sm' -t '%Y-%m-%d %H:%M:%S %z' "$path" 2>/dev/null || stat -c '%y' "$path" 2>/dev/null || printf 'unknown')" printf 'present bytes=%s modified=%s\n' "${bytes:-unknown}" "$modified" + elif [[ -e "$path" ]]; then + printf 'non-regular\n' else printf 'missing\n' fi @@ -65,12 +67,14 @@ file_summary() { marker_summary() { local path="$1" local marker="$2" - if [[ -e "$path" ]]; then + if [[ -f "$path" ]]; then if grep -Fq "$marker" "$path" 2>/dev/null; then printf 'marker-present\n' else printf 'marker-missing\n' fi + elif [[ -e "$path" ]]; then + printf 'non-regular\n' else printf 'missing\n' fi