/cmux-cua

name: cmux-cua
disable-model-invocation: true
description: "Use only after the user explicitly asks for Computer Use: 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 Computer Use. Wait for a direct user request to use 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.

• `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.

• Kill switch: set `CMUX_COMPUTER_USE_MCP_DISABLED=1`, or toggle it off in

Settings → Computer Use (persists to `~/.config/cmux/cmux.json` and is exported to spawned terminals).

• 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`).

Onboarding is opened only by a deliberate user action in Settings → Computer Use (the **Grant…** or **Open System Settings** permission controls), not by a tool call, skill load, prompt text, MCP discovery, cmux startup, or agent resume. Settings → Computer Use always shows the two authoritative permission states; choosing **Grant…** for an ungranted permission opens that same permission step and its draggable helper-app recovery path. Each **Allow** action opens the matching permanent System Settings pane in one step and stays labeled **Allow** until the helper reports the grant; pressing it again simply reopens the same pane. If macOS has not listed the helper yet, drag or add the **cmux Computer Use** app tile to the list, then turn it on. cmux reads status from th