[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6F4PMA5Z7FQKDBXTTY5MCZ2":3,"skill-same:01M6F4PMA5Z7FQKDBXTTY5MCZ2":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":29,"commitSha":55,"skillDirectory":56,"forksCount":57,"repositoryHtmlUrl":58,"repositoryHomepageUrl":6,"ownerHtmlUrl":59,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":60,"install":61,"resources":74},"01M6F4PMA5Z7FQKDBXTTY5MCZ2","cmux",null,"Control cmux workspaces, panes, surfaces, and agent sessions safely from macOS terminal workflows.","boisenoise\u002Fskills-collections","boisenoise","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F193180?v=4","01M6CDBDQK6BDN55ZMA6B6PKBM","01M6CDBDVSJ3JPTBYN26FZ7TZK",12,"MIT","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-cmux\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[5,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"2026","macos","blob","critical","control","agent sessions","main","community","surfaces","workspaces","panes","https","license","development","sessions","workflows","codex","github","terminal","2026-11-10 10:12:30",false,"---\nname: cmux\ndescription: \"Control cmux workspaces, panes, surfaces, and agent sessions safely from macOS terminal workflows.\"\ncategory: development\nrisk: critical\nsource: community\nsource_repo: davidondrej\u002Fskills\nsource_type: community\ndate_added: \"2026-07-07\"\nauthor: davidondrej\ntags: [cmux, terminal, agents, macos]\ntools: [claude, codex]\nlicense: \"MIT\"\nlicense_source: \"https:\u002F\u002Fgithub.com\u002Fdavidondrej\u002Fskills\u002Fblob\u002Fmain\u002FLICENSE\"\n---\n## Supporting material availability\n\nThis catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:\n\n- `\u003Csupport-root>\u002Freferences\u002Fsocket-api.md`\n\nObtain the required material from the [declared upstream source](https:\u002F\u002Fgithub.com\u002Fdavidondrej\u002Fskills), or from a user-provided installation of that source. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.\n\n\n# cmux Control\n\n## When to Use\n\n- Use when you need to inspect, create, close, or rearrange cmux panes, surfaces, or workspaces.\n- Use when you need to send input to or monitor agents running inside cmux.\n\ncmux is a native macOS terminal app for running multiple AI coding agents in parallel. It exposes a CLI (`cmux`) and a Unix-socket JSON-RPC API (`\u002Ftmp\u002Fcmux.sock`) for full topology and browser control.\n\n## Core Concepts\n\n- **Window** — top-level macOS cmux window\n- **Workspace** — sidebar tab within a window (one git branch \u002F project context)\n- **Pane** — split region inside a workspace\n- **Surface** — tab inside a pane (terminal or browser)\n\nHandles default to short refs (`workspace:2`, `pane:1`, `surface:7`); UUIDs accepted as input. Add `--id-format uuids|both` for UUID output.\n\n### Ref syntax — get this right or fail silently\n\n- **Always use PREFIXED refs** (`pane:38`, `surface:46`). A **bare number is treated as an INDEX, not an ID** — `--surface 46` means \"the surface at index 46\" (usually nonexistent → silent failure), NOT `surface:46`.\n- **`read-screen` and `capture-pane` have NO `--pane` flag** — they target `--workspace` or `--surface` only. Passing `--pane` errors, and a bare\u002Fmissing target falls back to your OWN surface (you'll read your own footer and draw wrong conclusions). To read a pane: resolve it to a surface FIRST with `cmux list-pane-surfaces --pane pane:N`, then `cmux read-screen --surface surface:N`.\n- **Never append `2>\u002Fdev\u002Fnull` to cmux commands.** Errors go to stderr with exit code 1; suppressing them blinds you to your own ref\u002Fflag mistakes (the #1 cause of \"(no output)\").\n\n## Detect cmux in a Shell\n\n```bash\n[ -S \"${CMUX_SOCKET_PATH:-\u002Ftmp\u002Fcmux.sock}\" ] || exit 0   # bail if not in cmux\n[ -n \"${CMUX_WORKSPACE_ID:-}\" ] && echo \"inside cmux surface\"\n```\n\nInjected env vars in every cmux-spawned terminal: `CMUX_WORKSPACE_ID`, `CMUX_SURFACE_ID`, `CMUX_SOCKET_PATH`, `CMUX_PORT`. **Always anchor automation to `CMUX_WORKSPACE_ID`** — the visually focused workspace may not be the agent's caller workspace.\n\nBefore using example refs, list actual topology and validate ownership. A workspace is not automatically a separate Git checkout; creating one does not isolate branch\u002Ffile changes. Verify each command against local help\u002Fcapabilities because these notes include version-specific workarounds.\n\n## Fast Start — Topology\n\n```bash\ncmux identify --json                              # who am I (window\u002Fworkspace\u002Fpane\u002Fsurface)\ncmux tree                                         # full hierarchy\ncmux list-workspaces --json\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux list-pane-surfaces --pane pane:1 # Resolve actual pane in caller workspace first\n\ncmux new-workspace --name \"feature-x\" --cwd \u002Fpath\u002Fto\u002Frepo\ncmux new-pane --workspace \"$CMUX_WORKSPACE_ID\" --type terminal --direction right --focus false\ncmux new-pane --workspace \"$CMUX_WORKSPACE_ID\" --type browser  --direction right --url http:\u002F\u002Flocalhost:3000\ncmux move-surface --surface surface:7 --pane pane:2 --focus false\ncmux split-off --surface surface:7 right\ncmux reorder-surface --surface surface:7 --before surface:3\ncmux close-surface --surface surface:7\n```\n\n## Polling Pi Agents in Panes — Keep Sleeps Short\n\nUse event-driven completion or bounded polling with backoff based on actual progress. No particular model\u002Fprovider, token speed or user setup is implied by this skill. Report meaningful changes rather than every unchanged poll.\n\nClaude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking.\n\n## Send Input\n\n**Command names:** there is NO `send-surface` \u002F `send-key-surface`. Target a specific surface with the `--surface` flag on `send` \u002F `send-key` (same commands as the focused terminal). `send-panel` \u002F `send-key-panel` exist ONLY for panels (`--panel`), not surfaces.\n\n```bash\n# Resolve and verify a task-owned surface first; never send commands or interrupts to whichever terminal is focused.\ncmux send --surface surface:7 \"npm run build\"               # specific surface (NOT send-surface)\ncmux send-key --surface surface:7 enter                     # specific surface (NOT send-key-surface)\n```\n\n## Notifications & Sidebar Metadata\n\n```bash\ncmux notify --title \"Done\" --body \"tests passed\"\ncmux set-status build \"compiling\" --icon hammer --color \"#ff9500\"\ncmux set-progress 0.5 --label \"Building...\"\ncmux log --level success \"All 42 tests passed\"               # info|progress|success|warning|error\ncmux trigger-flash --workspace \"$CMUX_WORKSPACE_ID\"          # blue-ring attention cue\ncmux sidebar-state --json                                    # dump all sidebar metadata\n```\n\n## Browser Automation (WKWebView)\n\nWorkflow: open → wait → snapshot → act → re-snapshot.\n\n```bash\nS=$(cmux --json browser open https:\u002F\u002Fexample.com | jq -r .result.surface_ref)\ncmux browser \"$S\" wait --load-state complete --timeout-ms 15000\ncmux browser \"$S\" snapshot --interactive                     # returns elements as e1, e2, ...\ncmux browser \"$S\" fill e1 \"\u003Cemail-address>\"\ncmux browser \"$S\" click e2 --snapshot-after\n\n# Navigation \u002F inspection\ncmux browser \"$S\" goto https:\u002F\u002Fexample.com # Other separate commands: back, forward, reload\ncmux browser \"$S\" get url # Run other get subcommands separately, after checking local help.\ncmux browser \"$S\" eval 'return document.title'\n\n# Waits\ncmux browser \"$S\" wait --selector \"#ready\" --timeout-ms 10000\ncmux browser \"$S\" wait --url-contains \"\u002Fdashboard\" --timeout-ms 10000\n\n# Session\n# Cookie\u002Fstate access can expose credentials; use only for an explicitly authorized auth-debug task.\n# Save state only into a private mode-0700 task directory with mode-0600 file; no shared \u002Ftmp\u002Fauth.json.\n\n# Diagnostics\ncmux browser \"$S\" console list # Run errors list or screenshot separately as needed.\n```\n\n**Not supported by WKWebView** (return `not_supported`): viewport emulation, geolocation\u002Foffline emulation, trace recording, network route interception, raw input injection.\n\n## Markdown Viewer\n\n```bash\ncmux markdown open plan.md --direction right                 # live-watching renderer\ncmux open file.pdf                                           # auto-routes to right viewer\n```\n\n`cmux markdown open` flags: `--workspace`, `--surface`, `--window`, `--direction \u003Cright|down|left|up>`, `--focus \u003Ctrue|false>`. There is **NO `--pane` flag** — passing it errors. To target a pane, pass `--surface \u003Cexisting-md-surface-in-that-pane>`.\n\n### Reuse the existing right markdown pane (don't spawn strays)\n\nDefault behavior of `markdown open` is to **create a new pane** every time, even with `--direction right`. To keep all docs as tabs in ONE right pane, follow this exactly:\n\n```bash\n# 1. Find the right pane and its surfaces (anchor to THIS workspace)\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux list-pane-surfaces --pane pane:10        # the right\u002Fhelper pane\n\n# 2. Open targeting an existing markdown surface IN that pane (reuses pane, adds tab)\ncmux markdown open \u002Fabs\u002Fpath\u002Ffile.md --surface surface:12 --focus false\n\n# 3. If it STILL spawned a new pane (it can), move the new surface in + verify\ncmux move-surface --surface surface:NEW --pane pane:10 --focus false\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"   # confirm stray pane is gone\n```\n\n### Swapping the file in the single right pane (close-FIRST, then open)\n\nTo replace the doc shown in your one right markdown pane, an upstream workaround is **close the previous surface FIRST, then `markdown open` the new file fresh** — never move an existing viewer, never open-then-close.\n\n```bash\n# 1. close the previous right markdown surface (right side goes empty)\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux close-surface --surface surface:PREV\n# 2. THEN open the new file fresh\ncmux markdown open \u002Fabs\u002Fpath\u002Fnew.md --direction right --focus false\n```\n\nVerify local behavior and ownership before closing any viewer; preserve unsaved work. Opening first then closing the old one, or `move-surface`-ing an existing viewer, leaves the right pane BLANK.\n\n### Hard-won lessons (avoid the trial-and-error)\n\n- **Surface refs are global, not per-workspace.** A ref like `surface:126` from an earlier `markdown open` may live in a different window\u002Fworkspace. Always re-list (`list-panes` \u002F `list-pane-surfaces`) before reusing a ref — never assume a ref from a previous turn is still in the right pane.\n- **`move-surface`-ing a markdown viewer often leaves it BLANK.** The moved surface keeps `type=markdown` and `surface-health` looks fine, but renders nothing. Fix: `close-surface` it and `cmux markdown open \u003Cpath>` fresh, then move the *fresh* surface if needed. Don't waste time on `refresh-surfaces` — it usually won't fix a moved-then-blank viewer.\n- **You cannot screenshot or `read-screen` a markdown surface** (`Surface is not a terminal` \u002F browser screenshot is WKWebView-only). To verify a markdown viewer rendered, ask the user or open the file in a browser surface instead. Don't burn turns trying to capture it.\n- **`cmux list-surfaces` does not exist.** Use `cmux list-pane-surfaces [--pane ...]`.\n\n## Settings & Config\n\n```bash\ncmux docs settings        # prints paths, schema URL, reload cmd — read BEFORE editing\ncmux settings path        # path to cmux.json\ncmux settings cmux-json   # open in editor\ncmux reload-config        # hot-reload cmux.json + ~\u002F.config\u002Fghostty\u002Fconfig (Cmd+Shift+,)\n```\n\nLocations:\n- cmux settings: `~\u002F.config\u002Fcmux\u002Fcmux.json` (canonical). Project-local override: `.cmux\u002Fcmux.json` or `.\u002Fcmux.json`.\n- Terminal rendering (font, cursor, theme, scrollback, opacity, blur): `~\u002F.config\u002Fghostty\u002Fconfig` — NOT cmux.json.\n\nBefore editing `cmux.json`, copy it to a timestamped `.bak` next to it so the user can revert. Schema: `https:\u002F\u002Fraw.githubusercontent.com\u002Fmanaflow-ai\u002Fcmux\u002Fmain\u002Fweb\u002Fdata\u002Fcmux.schema.json`.\n\n## Agent Hooks & Install\n\n```bash\nbrew tap manaflow-ai\u002Fcmux && brew install --cask cmux\n# Prefer the installed CLI\u002FPATH; do not force-replace an existing \u002Fusr\u002Flocal\u002Fbin\u002Fcmux.\ncmux hooks setup codex # Example: only the explicitly requested host, after reviewing changes.\n# Other supported host names are alternatives, not a shell pipeline; check local help.\nnpx skills add manaflow-ai\u002Fcmux -g -y                        # install cmux skills for agents\n```\n\nNative session-resume supported for: Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory, Qoder.\n\n## Socket API (advanced)\n\n`\u002Ftmp\u002Fcmux.sock` — Unix socket, JSON-RPC v2. Use for tight loops where subprocess spawn cost matters; otherwise prefer the CLI.\n\n```bash\necho '{\"id\":\"1\",\"method\":\"workspace.list\",\"params\":{}}' | nc -U \u002Ftmp\u002Fcmux.sock\n```\n\nMethod prefixes: `system.*`, `window.*`, `workspace.*`, `pane.*`, `surface.*`, `notification.*`, `browser.*`. Full list and Python client example in `references\u002Fsocket-api.md`.\n\nAccess modes: `cmuxOnly` (default — only cmux-spawned processes), `automation` (any local process), `password`, `allowAll` (unsafe). If you hit `Failed to connect to socket`, you're likely an external process under `cmuxOnly` — run from an authorized cmux terminal; broadening socket access needs explicit authorization and least-privilege configuration.\n\n## Critical Rules — Non-Disruptive Automation\n\nThese rules come from the `cmux-workspace` skill and prevent agents from yanking the user's focus:\n\n1. **Anchor to `CMUX_WORKSPACE_ID`.** Never assume the visually focused workspace is the target.\n2. **Never call focus-changing verbs speculatively.** `select-workspace`, `focus-pane`, `focus-panel`, `focus-surface` only on explicit user request. Pass `--focus false` whenever available.\n3. **Build layout additively in one call.** `cmux new-pane --type … --focus false` beats create-then-move-then-focus chains.\n4. **Right-side helper pane pattern.** Reuse an existing non-caller helper pane if present; otherwise create exactly one right-side pane.\n5. **Never send input to surfaces you don't own.** Only target surfaces in the caller's workspace unless the user explicitly asks for cross-workspace routing.\n6. **Check surface health before routing input** when UI state may be stale: `cmux surface-health`.\n\n## Common Pitfalls\n\n- **Pi\u002FPi-like socket connection failures from external processes** → default `cmuxOnly` mode; use an authorized cmux terminal; do not weaken socket access automatically.\n- **macOS only.** No Linux\u002FWindows port.\n- **WKWebView ≠ CDP.** Don't expect Playwright-equivalent network mocking or viewport emulation.\n- **Resume strips sensitive env vars.** Re-inject tokens at resume time if the agent needs them.\n- **Skills snapshot at app start.** Edits to skill files require a restart of the consuming agent.\n- **Legacy v1 socket payloads (`{\"command\":...}`) rejected.** Use v2 JSON-RPC only.\n- **Don't `cat ~\u002F.cmuxterm\u002F*-hook-sessions.json`** expecting secrets — they're scrubbed. Look there for session\u002Fsurface mappings only.\n\n## Reference: Full CLI Help\n\nFor any command, `cmux \u003Ccmd> --help` is authoritative. Use `cmux capabilities --json` to enumerate available socket methods in the current build.\n\n## Keyboard Shortcuts (most-used)\n\nWorkspaces: ⌘N new, ⌘1–8 jump, ⌃⌘[ \u002F ⌃⌘] prev\u002Fnext, ⌘⇧W close, ⌘B sidebar.\nSurfaces: ⌘T new, ⌘⇧[ \u002F ⌘⇧] prev\u002Fnext, ⌘W close, ⌃1–8 jump.\nSplits: ⌘D right, ⌘⇧D down, ⌥⌘D browser right, ⌥⌘←→↑↓ focus directional, ⌘⇧↵ zoom.\nBrowser: ⌘⇧L open, ⌘L address bar, ⌘[\u002F⌘] back\u002Fforward, ⌥⌘I devtools.\nApp: ⌘, settings, ⌘⇧, reload-config, ⌘⇧P palette, ⌘⇧O restore session, ⌃⌥⌘. system-wide show\u002Fhide.\n\n## Limitations\n\n- Adapted from `davidondrej\u002Fskills`; verify local paths, tools, credentials, and agent features before acting.\n- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.\n","## Supporting material availability\n\nThis catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:\n\n- `\u003Csupport-root>\u002Freferences\u002Fsocket-api.md`\n\nObtain the required material from the [declared upstream source](https:\u002F\u002Fgithub.com\u002Fdavidondrej\u002Fskills), or from a user-provided installation of that source. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.\n\n\n# cmux Control\n\n## When to Use\n\n- Use when you need to inspect, create, close, or rearrange cmux panes, surfaces, or workspaces.\n- Use when you need to send input to or monitor agents running inside cmux.\n\ncmux is a native macOS terminal app for running multiple AI coding agents in parallel. It exposes a CLI (`cmux`) and a Unix-socket JSON-RPC API (`\u002Ftmp\u002Fcmux.sock`) for full topology and browser control.\n\n## Core Concepts\n\n- **Window** — top-level macOS cmux window\n- **Workspace** — sidebar tab within a window (one git branch \u002F project context)\n- **Pane** — split region inside a workspace\n- **Surface** — tab inside a pane (terminal or browser)\n\nHandles default to short refs (`workspace:2`, `pane:1`, `surface:7`); UUIDs accepted as input. Add `--id-format uuids|both` for UUID output.\n\n### Ref syntax — get this right or fail silently\n\n- **Always use PREFIXED refs** (`pane:38`, `surface:46`). A **bare number is treated as an INDEX, not an ID** — `--surface 46` means \"the surface at index 46\" (usually nonexistent → silent failure), NOT `surface:46`.\n- **`read-screen` and `capture-pane` have NO `--pane` flag** — they target `--workspace` or `--surface` only. Passing `--pane` errors, and a bare\u002Fmissing target falls back to your OWN surface (you'll read your own footer and draw wrong conclusions). To read a pane: resolve it to a surface FIRST with `cmux list-pane-surfaces --pane pane:N`, then `cmux read-screen --surface surface:N`.\n- **Never append `2>\u002Fdev\u002Fnull` to cmux commands.** Errors go to stderr with exit code 1; suppressing them blinds you to your own ref\u002Fflag mistakes (the #1 cause of \"(no output)\").\n\n## Detect cmux in a Shell\n\n```bash\n[ -S \"${CMUX_SOCKET_PATH:-\u002Ftmp\u002Fcmux.sock}\" ] || exit 0   # bail if not in cmux\n[ -n \"${CMUX_WORKSPACE_ID:-}\" ] && echo \"inside cmux surface\"\n```\n\nInjected env vars in every cmux-spawned terminal: `CMUX_WORKSPACE_ID`, `CMUX_SURFACE_ID`, `CMUX_SOCKET_PATH`, `CMUX_PORT`. **Always anchor automation to `CMUX_WORKSPACE_ID`** — the visually focused workspace may not be the agent's caller workspace.\n\nBefore using example refs, list actual topology and validate ownership. A workspace is not automatically a separate Git checkout; creating one does not isolate branch\u002Ffile changes. Verify each command against local help\u002Fcapabilities because these notes include version-specific workarounds.\n\n## Fast Start — Topology\n\n```bash\ncmux identify --json                              # who am I (window\u002Fworkspace\u002Fpane\u002Fsurface)\ncmux tree                                         # full hierarchy\ncmux list-workspaces --json\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux list-pane-surfaces --pane pane:1 # Resolve actual pane in caller workspace first\n\ncmux new-workspace --name \"feature-x\" --cwd \u002Fpath\u002Fto\u002Frepo\ncmux new-pane --workspace \"$CMUX_WORKSPACE_ID\" --type terminal --direction right --focus false\ncmux new-pane --workspace \"$CMUX_WORKSPACE_ID\" --type browser  --direction right --url http:\u002F\u002Flocalhost:3000\ncmux move-surface --surface surface:7 --pane pane:2 --focus false\ncmux split-off --surface surface:7 right\ncmux reorder-surface --surface surface:7 --before surface:3\ncmux close-surface --surface surface:7\n```\n\n## Polling Pi Agents in Panes — Keep Sleeps Short\n\nUse event-driven completion or bounded polling with backoff based on actual progress. No particular model\u002Fprovider, token speed or user setup is implied by this skill. Report meaningful changes rather than every unchanged poll.\n\nClaude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking.\n\n## Send Input\n\n**Command names:** there is NO `send-surface` \u002F `send-key-surface`. Target a specific surface with the `--surface` flag on `send` \u002F `send-key` (same commands as the focused terminal). `send-panel` \u002F `send-key-panel` exist ONLY for panels (`--panel`), not surfaces.\n\n```bash\n# Resolve and verify a task-owned surface first; never send commands or interrupts to whichever terminal is focused.\ncmux send --surface surface:7 \"npm run build\"               # specific surface (NOT send-surface)\ncmux send-key --surface surface:7 enter                     # specific surface (NOT send-key-surface)\n```\n\n## Notifications & Sidebar Metadata\n\n```bash\ncmux notify --title \"Done\" --body \"tests passed\"\ncmux set-status build \"compiling\" --icon hammer --color \"#ff9500\"\ncmux set-progress 0.5 --label \"Building...\"\ncmux log --level success \"All 42 tests passed\"               # info|progress|success|warning|error\ncmux trigger-flash --workspace \"$CMUX_WORKSPACE_ID\"          # blue-ring attention cue\ncmux sidebar-state --json                                    # dump all sidebar metadata\n```\n\n## Browser Automation (WKWebView)\n\nWorkflow: open → wait → snapshot → act → re-snapshot.\n\n```bash\nS=$(cmux --json browser open https:\u002F\u002Fexample.com | jq -r .result.surface_ref)\ncmux browser \"$S\" wait --load-state complete --timeout-ms 15000\ncmux browser \"$S\" snapshot --interactive                     # returns elements as e1, e2, ...\ncmux browser \"$S\" fill e1 \"\u003Cemail-address>\"\ncmux browser \"$S\" click e2 --snapshot-after\n\n# Navigation \u002F inspection\ncmux browser \"$S\" goto https:\u002F\u002Fexample.com # Other separate commands: back, forward, reload\ncmux browser \"$S\" get url # Run other get subcommands separately, after checking local help.\ncmux browser \"$S\" eval 'return document.title'\n\n# Waits\ncmux browser \"$S\" wait --selector \"#ready\" --timeout-ms 10000\ncmux browser \"$S\" wait --url-contains \"\u002Fdashboard\" --timeout-ms 10000\n\n# Session\n# Cookie\u002Fstate access can expose credentials; use only for an explicitly authorized auth-debug task.\n# Save state only into a private mode-0700 task directory with mode-0600 file; no shared \u002Ftmp\u002Fauth.json.\n\n# Diagnostics\ncmux browser \"$S\" console list # Run errors list or screenshot separately as needed.\n```\n\n**Not supported by WKWebView** (return `not_supported`): viewport emulation, geolocation\u002Foffline emulation, trace recording, network route interception, raw input injection.\n\n## Markdown Viewer\n\n```bash\ncmux markdown open plan.md --direction right                 # live-watching renderer\ncmux open file.pdf                                           # auto-routes to right viewer\n```\n\n`cmux markdown open` flags: `--workspace`, `--surface`, `--window`, `--direction \u003Cright|down|left|up>`, `--focus \u003Ctrue|false>`. There is **NO `--pane` flag** — passing it errors. To target a pane, pass `--surface \u003Cexisting-md-surface-in-that-pane>`.\n\n### Reuse the existing right markdown pane (don't spawn strays)\n\nDefault behavior of `markdown open` is to **create a new pane** every time, even with `--direction right`. To keep all docs as tabs in ONE right pane, follow this exactly:\n\n```bash\n# 1. Find the right pane and its surfaces (anchor to THIS workspace)\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux list-pane-surfaces --pane pane:10        # the right\u002Fhelper pane\n\n# 2. Open targeting an existing markdown surface IN that pane (reuses pane, adds tab)\ncmux markdown open \u002Fabs\u002Fpath\u002Ffile.md --surface surface:12 --focus false\n\n# 3. If it STILL spawned a new pane (it can), move the new surface in + verify\ncmux move-surface --surface surface:NEW --pane pane:10 --focus false\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"   # confirm stray pane is gone\n```\n\n### Swapping the file in the single right pane (close-FIRST, then open)\n\nTo replace the doc shown in your one right markdown pane, an upstream workaround is **close the previous surface FIRST, then `markdown open` the new file fresh** — never move an existing viewer, never open-then-close.\n\n```bash\n# 1. close the previous right markdown surface (right side goes empty)\ncmux list-panes --workspace \"$CMUX_WORKSPACE_ID\"\ncmux close-surface --surface surface:PREV\n# 2. THEN open the new file fresh\ncmux markdown open \u002Fabs\u002Fpath\u002Fnew.md --direction right --focus false\n```\n\nVerify local behavior and ownership before closing any viewer; preserve unsaved work. Opening first then closing the old one, or `move-surface`-ing an existing viewer, leaves the right pane BLANK.\n\n### Hard-won lessons (avoid the trial-and-error)\n\n- **Surface refs are global, not per-workspace.** A ref like `surface:126` from an earlier `markdown open` may live in a different window\u002Fworkspace. Always re-list (`list-panes` \u002F `list-pane-surfaces`) before reusing a ref — never assume a ref from a previous turn is still in the right pane.\n- **`move-surface`-ing a markdown viewer often leaves it BLANK.** The moved surface keeps `type=markdown` and `surface-health` looks fine, but renders nothing. Fix: `close-surface` it and `cmux markdown open \u003Cpath>` fresh, then move the *fresh* surface if needed. Don't waste time on `refresh-surfaces` — it usually won't fix a moved-then-blank viewer.\n- **You cannot screenshot or `read-screen` a markdown surface** (`Surface is not a terminal` \u002F browser screenshot is WKWebView-only). To verify a markdown viewer rendered, ask the user or open the file in a browser surface instead. Don't burn turns trying to capture it.\n- **`cmux list-surfaces` does not exist.** Use `cmux list-pane-surfaces [--pane ...]`.\n\n## Settings & Config\n\n```bash\ncmux docs settings        # prints paths, schema URL, reload cmd — read BEFORE editing\ncmux settings path        # path to cmux.json\ncmux settings cmux-json   # open in editor\ncmux reload-config        # hot-reload cmux.json + ~\u002F.config\u002Fghostty\u002Fconfig (Cmd+Shift+,)\n```\n\nLocations:\n- cmux settings: `~\u002F.config\u002Fcmux\u002Fcmux.json` (canonical). Project-local override: `.cmux\u002Fcmux.json` or `.\u002Fcmux.json`.\n- Terminal rendering (font, cursor, theme, scrollback, opacity, blur): `~\u002F.config\u002Fghostty\u002Fconfig` — NOT cmux.json.\n\nBefore editing `cmux.json`, copy it to a timestamped `.bak` next to it so the user can revert. Schema: `https:\u002F\u002Fraw.githubusercontent.com\u002Fmanaflow-ai\u002Fcmux\u002Fmain\u002Fweb\u002Fdata\u002Fcmux.schema.json`.\n\n## Agent Hooks & Install\n\n```bash\nbrew tap manaflow-ai\u002Fcmux && brew install --cask cmux\n# Prefer the installed CLI\u002FPATH; do not force-replace an existing \u002Fusr\u002Flocal\u002Fbin\u002Fcmux.\ncmux hooks setup codex # Example: only the explicitly requested host, after reviewing changes.\n# Other supported host names are alternatives, not a shell pipeline; check local help.\nnpx skills add manaflow-ai\u002Fcmux -g -y                        # install cmux skills for agents\n```\n\nNative session-resume supported for: Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory, Qoder.\n\n## Socket API (advanced)\n\n`\u002Ftmp\u002Fcmux.sock` — Unix socket, JSON-RPC v2. Use for tight loops where subprocess spawn cost matters; otherwise prefer the CLI.\n\n```bash\necho '{\"id\":\"1\",\"method\":\"workspace.list\",\"params\":{}}' | nc -U \u002Ftmp\u002Fcmux.sock\n```\n\nMethod prefixes: `system.*`, `window.*`, `workspace.*`, `pane.*`, `surface.*`, `notification.*`, `browser.*`. Full list and Python client example in `references\u002Fsocket-api.md`.\n\nAccess modes: `cmuxOnly` (default — only cmux-spawned processes), `automation` (any local process), `password`, `allowAll` (unsafe). If you hit `Failed to connect to socket`, you're likely an external process under `cmuxOnly` — run from an authorized cmux terminal; broadening socket access needs explicit authorization and least-privilege configuration.\n\n## Critical Rules — Non-Disruptive Automation\n\nThese rules come from the `cmux-workspace` skill and prevent agents from yanking the user's focus:\n\n1. **Anchor to `CMUX_WORKSPACE_ID`.** Never assume the visually focused workspace is the target.\n2. **Never call focus-changing verbs speculatively.** `select-workspace`, `focus-pane`, `focus-panel`, `focus-surface` only on explicit user request. Pass `--focus false` whenever available.\n3. **Build layout additively in one call.** `cmux new-pane --type … --focus false` beats create-then-move-then-focus chains.\n4. **Right-side helper pane pattern.** Reuse an existing non-caller helper pane if present; otherwise create exactly one right-side pane.\n5. **Never send input to surfaces you don't own.** Only target surfaces in the caller's workspace unless the user explicitly asks for cross-workspace routing.\n6. **Check surface health before routing input** when UI state may be stale: `cmux surface-health`.\n\n## Common Pitfalls\n\n- **Pi\u002FPi-like socket connection failures from external processes** → default `cmuxOnly` mode; use an authorized cmux terminal; do not weaken socket access automatically.\n- **macOS only.** No Linux\u002FWindows port.\n- **WKWebView ≠ CDP.** Don't expect Playwright-equivalent network mocking or viewport emulation.\n- **Resume strips sensitive env vars.** Re-inject tokens at resume time if the agent needs them.\n- **Skills snapshot at app start.** Edits to skill files require a restart of the consuming agent.\n- **Legacy v1 socket payloads (`{\"command\":...}`) rejected.** Use v2 JSON-RPC only.\n- **Don't `cat ~\u002F.cmuxterm\u002F*-hook-sessions.json`** expecting secrets — they're scrubbed. Look there for session\u002Fsurface mappings only.\n\n## Reference: Full CLI Help\n\nFor any command, `cmux \u003Ccmd> --help` is authoritative. Use `cmux capabilities --json` to enumerate available socket methods in the current build.\n\n## Keyboard Shortcuts (most-used)\n\nWorkspaces: ⌘N new, ⌘1–8 jump, ⌃⌘[ \u002F ⌃⌘] prev\u002Fnext, ⌘⇧W close, ⌘B sidebar.\nSurfaces: ⌘T new, ⌘⇧[ \u002F ⌘⇧] prev\u002Fnext, ⌘W close, ⌃1–8 jump.\nSplits: ⌘D right, ⌘⇧D down, ⌥⌘D browser right, ⌥⌘←→↑↓ focus directional, ⌘⇧↵ zoom.\nBrowser: ⌘⇧L open, ⌘L address bar, ⌘[\u002F⌘] back\u002Fforward, ⌥⌘I devtools.\nApp: ⌘, settings, ⌘⇧, reload-config, ⌘⇧P palette, ⌘⇧O restore session, ⌃⌥⌘. system-wide show\u002Fhide.\n\n## Limitations\n\n- Adapted from `davidondrej\u002Fskills`; verify local paths, tools, credentials, and agent features before acting.\n- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.\n",{"name":5,"risk":26,"tags":47,"tools":49,"author":51,"source":30,"license":14,"category":36,"date_added":52,"description":7,"source_repo":53,"source_type":30,"license_source":54},[5,41,48,24],"agents",[50,39],"claude","davidondrej","2026-07-07","davidondrej\u002Fskills","https:\u002F\u002Fgithub.com\u002Fdavidondrej\u002Fskills\u002Fblob\u002Fmain\u002FLICENSE","7bf2279c8a65758319526a721d5c4b75683aec9c","skills\u002Fantigravity-cmux",3,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections","https:\u002F\u002Fgithub.com\u002Fboisenoise","2026-11-10 14:20:15",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add boisenoise\u002Fskills-collections --skill cmux",{"tool":67,"command":68},"bunx","bunx skills add boisenoise\u002Fskills-collections --skill cmux",{"tool":70,"command":71},"pnpm","pnpm dlx skills add boisenoise\u002Fskills-collections --skill cmux","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-cmux\u002FSKILL.md",true,[],[76,103,124,149,168,191],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":81,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":42},"01M6WNH92BHVFXHGPDZCPJ0AG0","web-access","Use Treg for public web or platform data only when existing search, browser and connected tools cannot cover the task, with explicit cost and data boundaries.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-web-access\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-web-access\u002FSKILL.md",[],[85,86,87,88,36,89,90,91,92,93,94,95,96,97,98,26,99,100,101,102,23],"web","access","web access","official","browser","search","data","Tools","read","fetch","only","youtube","free tools","platform","free","cover","normal","when",{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":107,"sourceHtmlUrl":108,"categories":109,"keywords":111,"publishedAt":42},"01M6WNF9XAYAB2CZDDJBAKNM93","treg","Use the Treg CLI or MCP catalog to discover, price and call authorized external tools with team-scoped credentials and a user-approved budget.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-treg\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-treg\u002FSKILL.md",[110],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[105,112,113,40,88,36,35,92,114,115,116,117,118,119,120,26,121,122,123,25,23],"MCP","cli","Budget","credentials","team","catalog","use","call","discover","external tools","with","scoped",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":128,"sourceHtmlUrl":129,"categories":130,"keywords":136,"publishedAt":42},"01M6WN93MEAZ4E41DYAHJRPHQT","recruit","Turn a job description into an evidence-linked candidate shortlist through Treg, with job-related ranking and optional authorized business contact enrichment.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-recruit\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-recruit\u002FSKILL.md",[131],{"categoryNo":132,"categoryName":133,"taxonomyType":134,"taxonomyTypeDesc":135},"01JBSEEDCAT000000000000038","人力资源","PROFESSION","适用职业",[126,40,88,35,34,137,138,139,140,141,26,142,143,144,122,145,146,147,148,25,105,23],"email","enrichment","business","evidence","phone","ranking","post","job description","for","person","candidate","reason",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":153,"sourceHtmlUrl":154,"categories":155,"keywords":156,"publishedAt":42},"01M6WN8R5RXSMHM9B4D9FAFX42","rea-growth","Analyze a company’s public growth and content through Treg, distinguish observations from hypotheses, and produce an evidence-linked playbook within an approved budget.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-rea-growth\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-rea-growth\u002FSKILL.md",[],[157,158,159,40,88,35,160,161,34,162,114,163,164,165,140,26,166,167,25,105,23],"growth","rea","rea growth","produce","content","playbook","marketing","analyze","public","observations","company",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":172,"sourceHtmlUrl":173,"categories":174,"keywords":175,"publishedAt":42},"01M6WN2EVE3RQRGWAKBT4S7YT2","make-ugc","Create original AI UGC-style product videos through Treg: research hooks, approve a licensed presenter and voice, generate clips, add captions and report costs.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-make-ugc\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-make-ugc\u002FSKILL.md",[],[176,177,40,178,88,179,35,180,181,182,183,184,26,185,186,187,188,189,190,25],"make","make ugc","research","create","Video","Captions","ads","short","hooks","head","style","niche","trending","talking-head","approve",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":80,"licenseFileUrl":195,"sourceHtmlUrl":196,"categories":197,"keywords":198,"publishedAt":42},"01M6WN10ARAA63Y8K1YNGXJ2RM","lead-signals","Find and qualify public buying signals through Treg, rank fitting business accounts and optionally enrich authorized business contact information.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-lead-signals\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-lead-signals\u002FSKILL.md",[],[199,200,201,40,88,35,202,203,139,204,205,26,206,207,208,209,210,211,212,25],"signals","lead","lead signals","how","find","ready","as","how to","qualify","people","information","enrich","changes","funding"]