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.

## 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.
  No user setup per session — start `claude` or `codex` inside cmux and the
  corresponding tool profile is there.
- `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.
- The wrappers keep the signed, app-bundled skill discoverable in both agent
  pickers: each repairs the link in its agent's own root before launching —
  `~/.claude/skills/cmux-cua` for Claude, `~/.agents/skills/cmux-cua` for
  Codex (migrating any older cmux-owned `cmux-computer-use` link) — so the
  picker shows one plain `cmux-cua` entry. Codex falls back to an
  invocation-scoped `skills.config` entry only when that repair fails; there
  is deliberately no Claude plugin fallback and no plugin manifest in this
  directory, because a manifest makes Codex namespace the skill
  (`cmux-cua:cmux-cua`) and Claude display it plugin-qualified. A user-owned
  directory or unrelated symlink at that path is never replaced. Set
  `CMUX_COMPUTER_USE_INSTALL_GLOBAL_SKILL=0` when a strictly session-local
  launch is required.
- 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 appears on the first real Computer Use tool invocation, not on cmux
or agent startup. 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 re-triggers it: cmux invalidates its cached
direct-capture-ready flag whenever it replaces the installed helper build,
which re-presents onboarding so the alert always lands with its explanation.
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.

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 ap