/cmux-cua

name: cmux-cua
disable-model-invocation: true
description: "Use only after the user explicitly asks for cmux Computer Use through the cmux-cua skill: drive real macOS apps from a cmux agent session via the bundled engine (accessibility tree + screenshots, click/type/scroll/drag, branded cursor), or explain its user-directed permission setup. Reading or discovering this skill is not consent."

cmux-cua

cmux bundles a local computer-use engine (packaged as `cmux Computer Use` with the MCP proxy named `cmux-cua`, from a pinned build of the `manaflow-ai/cmux-cua` fork) and attaches it as an MCP tool server named `cmux-cua` to every agent session cmux launches (Claude Code, Codex). The agent can then perceive and operate real macOS apps: read the accessibility tree, take screenshots, and click / type / scroll / drag.

Everything runs locally through the bundled **cmux Computer Use** helper. The helper has its own TCC identity, so Accessibility and Screen Recording never belong to the main cmux app and granting Screen Recording never requires restarting cmux. Upstream telemetry and update checks are disabled at runtime.

Do not invoke this skill, start its helper, request permissions, or perform a GUI action when the user is only reading, asking about, quoting, or mentioning cmux Computer Use. Wait for a direct user request to use cmux Computer Use; missing tools or permissions are not a reason to begin setup automatically.

How it attaches

• The `cmux-claude-wrapper` and `cmux-codex-wrapper` inject `cmux-cua` as an

MCP proxy using `mcp --socket <cmux-owned socket>` plus cursor-branding and state-dir env. Codex launches the exact tag-installed helper executable as its authenticated approval broker; Claude uses the bundled native-profile proxy client. The Codex wrapper additionally passes `--codex-computer-use-compat`; the Claude wrapper deliberately does not. Attachment availability is not user consent: merely starting an agent or discovering this skill is not a request to use it, and it must not open a permission window or perform GUI work.

• In Codex sessions launched by cmux, the wrapper disables Codex's native

`computer_use` provider. When the user says `$cmux-cua`, use only the namespaced `cmux-cua` MCP tools below. Never substitute Codex's built-in `computer` tool, another CUA connector, or a direct helper launch. If the `cmux-cua` tools are absent or unavailable, report that they are unavailable and stop; do not silently switch providers.

• `ComputerUseRuntimeService` is the only helper lifecycle owner. It installs

the nested helper under the tag-scoped `~/Library/Application Support/cmux/cmux-cua/helper/<scope>/` directory and launches that explicit app URL through LaunchServices.

• The native daemon uses the tag-scoped

`/tmp/cmux-cua-<uid>/<scope>/cmux-cua.sock`; the Codex compatibility daemon uses `cmux-cua-codex.sock` beside it. Both fit Darwin's Unix-socket path limit and share the tag-scoped cmux Application Support state directory.

• Neither wrapper installs global skills or adds skill directories by default.

Use the agent's normal skill installer for a persistent user-owned installation. Alternatively, `CMUX_COMPUTER_USE_INSTALL_GLOBAL_SKILL=1` requests an app-managed global link for that launch (`~/.agents/skills/cmux-cua` for Codex or `~/.claude/skills/cmux-cua` for Claude). Export the flag to retain these links on future launches; they may also appear outside cmux. Unset or `=0` removes only verified app-managed links. Project and user-owned skills take precedence, with no competing global install or automatic fallback. Codex 0.153 does not discover new paths from `skills.config`; no Claude projection or plugin fallback is used. Migration of the canonical and legacy `cmux-computer-use` / `codex-cua` links requires an existing cmux bundle ID, known install/build root, and root/current-user ownership. Unknown or dangling targets, real skill directories, unrelated symlinks, and project paths are preserved. `CMUX_CUA_DIAGNOSTICS=1` identifies preserved paths blocking explicit install and verified managed links retired by the per-launch policy. Historical app-created and manually-created symlinks with identical verified targets cannot be distinguished retroactively; recognized app-bundle links are treated as cmux-managed, while unknown and dangling links are preserved.

• While Computer Use is enabled, the helper daemon starts quietly at cmux

startup with its internal permission gate disabled. Starting cmux or an agent never requests access or shows onboarding.

• Wrappers are pure forced proxies. They never copy or launch the helper and

never fall back to in-process computer use. cmux owns the onboarding window and opens the permanent macOS permission panes directly; it does not ask the helper to raise an intermediate native prompt. The proxy keeps its external-flow flag on so the first driving call waits for both helper grants before it is forwarded.

• An explicit functional `$cmux-cua` request is the opt-in: if the saved

Computer Use toggle is off, cmux enables the runtime and opens onboarding automatically. The hard kill switch is `CMUX_COMPUTER_USE_MCP_DISABLED=1` (or managed policy); turning the Settings toggle off only stops automatic helper startup until the next explicit request.

• Attaches only on cmux-launched, live-socket sessions (same authority bar as

cmux hooks); hooks-disabled and stale-socket sessions do not attach.

Permissions (one-time, granted to the helper)

Two macOS permissions are required and are owned by **cmux Computer Use**, not the main cmux app:

• **Accessibility** — inspect and drive app UI (`AXIsProcessTrusted`).
• **Screen Recording** — screenshots / vision (`CGPreflightScreenCaptureAccess`).

When the user has asked for cmux Computer Use through this skill, the first functional tool call from a current cmux agent session opens setup au