Cmux Cua

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 the helper over its Unix socket, advances beside System Settings to the next missing permission, and shows completion in place once both are granted. On macOS Tahoe a third confirmation follows Screen Recording: the system's direct-capture consent, an alert that says cmux Computer Use "is attempting to bypass the system private window picker". That alert is expected — it comes from onboarding's host-authenticated capture probe, onboarding explains it in place, and the user must allow it before setup completes. Never "fix" it by suppressing the probe; without that consent, agent screenshots on Tahoe fail. The consent follows the helper's code signature, so every rebuilt (ad-hoc signed) dev helper can require the direct-capture step again: cmux invalidates its cached direct-capture-ready flag whenever it replaces the installed helper build. This remains quiet until the user deliberately re-enters Settings; helper replacement never presents onboarding on its own. Do not invoke check_permissions {prompt:true} or any standalone helper while this flow is active: that creates the stray native permission dialogs this onboarding deliberately avoids. The main cmux process never calls a TCC API or executes the cmux-cua binary.

If an already-attached proxy is unconfigured, its protected call remains quiet and returns the helper's setup-required response after its bounded readiness wait: “Computer Use onboarding is still in progress. Finish setup in cmux, then retry.” Re-enter Settings deliberately to start setup; do not try to grant consent by calling a setup/status tool.

A TCC prompt naming Codex Computer Use (com.openai.sky.CUAService) is not from cmux. The codex CLI ships its own computer-use helper; when codex runs inside a cmux terminal and pokes that helper with an Apple Event, macOS attributes the request to the responsible parent — the cmux app — so the dialog reads as cmux asking to control "Codex Computer Use". Nothing in cmux or the cmux-cua engine references that service; denying the prompt does not affect cmux computer use.

If actions fail with a permission error, grant Accessibility to cmux Computer Use. If screenshots come back blank, grant Screen Recording to cmux Computer Use. The helper daemon refreshes/restarts to pick up the grant while cmux stays