cmux-cua

어떤 스킬인가요?

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.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: "cmux-cua"
  short_description: "User-invoked cmux Computer Use for local macOS apps."
  default_prompt: "After the user explicitly requests it, use $cmux-cua to drive a local macOS app; otherwise do not invoke or set up Computer Use."

policy:
  allow_implicit_invocation: false

#!/usr/bin/env bash
# Shared, ownership-safe skill-link policy for the Claude and Codex wrappers.
#
# This file is bundled inside the signed cmux-cua resource and sourced by both
# wrappers. It deliberately has no launch side effects until
# cmux_cua_skill_reconcile is called by a cmux-owned session.


cmux_cua_skill_readlink() {
    /usr/bin/readlink "$1" 2>/dev/null || /bin/readlink "$1" 2>/dev/null
}

cmux_cua_skill_lexical_normalize() {
    local path="$1"
    [[ "$path" = /* ]] || return 1
    local normalized="/"
    local remaining="${path#/}"
    local component
    while [[ -n "$remaining" ]]; do
        if [[ "$remaining" == */* ]]; then
            component="${remaining%%/*}"
            remaining="${remaining#*/}"
        else
            component="$remaining"
            remaining=""
        fi
        case "$component" in
            ""|.) continue ;;
            ..)
                if [[ "$normalized" != "/" ]]; then
                    normalized="${normalized%/*}"
                    [[ -n "$normalized" ]] || normalized="/"
                fi
                ;;
            *)
                if [[ "$normalized" == "/" ]]; then
                    normalized="/$component"
                else
                    normalized="$normalized/$component"
                fi
                ;;
        esac
    done
    printf '%s' "$normalized"
}

cmux_cua_skill_resolve_link_target() {
    local link="$1"
    local target="$2"
    local resolved
    if [[ "$target" = /* ]]; then
        resolved="$target"
    else
        resolved="${link%/*}/$target"
    fi
    cmux_cua_skill_lexical_normalize "$resolved"
}

cmux_cua_skill_canonical_document() {
    local path="$1"
    [[ "$path" = /* ]] || return 1
    if [[ -f "$path" ]]; then
        local parent="${path%/*}"
        local basename="${path##*/}"
        local canonical_parent
        canonical_parent="$(cd "$parent" 2>/dev/null && pwd -P)" || canonical_parent=""
        if [[ -n "$canonical_parent" ]]; then
            printf '%s/%s' "$canonical_parent" "$basename"
            return 0
        fi
    fi
    cmux_cua_skill_lexical_normalize "$path"
}

cmux_cua_skill_frontmatter_name() {
    local file="$1"
    [[ -f "$file" ]] || return 1
    local awk_bin=/usr/bin/awk
    [[ -x "$awk_bin" ]] || awk_bin=awk
    "$awk_bin" '
        NR == 1 && $0 ~ /^---[[:space:]]*$/ { in_frontmatter = 1; next }
        in_frontmatter && $0 ~ /^---[[:space:]]*$/ { exit }
        in_frontmatter && $0 ~ /^name:[[:space:]]*/ {
            value = $0
            sub(/^name:[[:space:]]*/, "", value)
            gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
            print value
            exit
        }
    ' "$file" 2>/dev/null
}

cmux_cua_skill_name_is() {
    local file="$1"
    local expected="$2"
    local value
    value="$(cmux_cua_skill_frontmatter_name "$file")" || return 1
    value="${value#\"}"
    value="${value%\"}"
    value="${value#\'}"
    value="${value%\'}"
    [[ "$value" == "$expected" ]]
}

cmux_cua_skill_target_is_managed() {
    # A resource suffix, app name, or dangling path alone is not ownership
    # proof. A link is managed only when its existing bundle has cmux's bundle
    # identifier, lives in a known cmux install/build root, and is owned by
    # root or the current user. Removed bundles have no verifiable owner or
    # identity and are deliberately preserved for manual review.
    local target="$1"
    local resource_name
    case "$target" in
        */Contents/Resources/cmux-cua) resource_name=cmux-cua ;;
        */Contents/Resources/cmux-computer-use) resource_name=cmux-computer-use ;;
        */Contents/Resources/codex-cua) resource_name=codex-cua ;;
        *) return 1 ;;
    esac

    local app_bundle="${target%/Contents/Resources/$resource_name}"
    [[ "$app_bundle" == *.app ]] || return 1
    local home="${HOME:-}"
    local app_owner
    app_owner="$(/usr/bin/stat -f '%u' "$app_bundle" 2>/dev/null || true)"
    [[ "$app_owner" == "0" || "$app_owner" == "$(/usr/bin/id -u)" ]] || return 1

    case "$app_bundle" in
        /Applications/cmux*.app|/Applications/Utilities/cmux*.app|\
        "$home/Applications"/cmux*.app|\
        "$home/Library/Developer/Xcode/DerivedData"/cmux-*/Build/Products/*/cmux*.app|\
        /tmp/cmux-*/Build/Products/*/cmux*.app)
            ;;
        *)
            return 1
            ;;
    esac

    local info_plist="$app_bundle/Contents/Info.plist"
    if [[ -f "$info_plist" && -x /usr/libexec/PlistBuddy ]]; then
        local bundle_id
        bundle_id="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$info_plist" 2>/dev/null)" || return 1
        [[ "$bundle_id" == com.cmuxterm.* ]]
        return $?
    fi
    return 1
}

cmux_cua_skill_link_is_managed() {
    local link="$1"
    [[ -L "$link" ]] || return 1
    local target resolved
    target="$(cmux_cua_skill_readlink "$link")" || return 1
    [[ -n "$target" ]] || return 1
    resolved="$(cmux_cua_skill_resolve_link_target "$link" "$target")" || resolved="$target"
    cmux_cua_skill_target_is_managed "$resolved" || cmux_cua_skill_target_is_managed "$target"
}

cmux_cua_skill_remove_managed_link() {
    local link="$1"
    if cmux_cua_skill_link_is_managed "$link"; then
        # rm acts on the link itself because the target was validated and the
        # operand is an absolute path. Never recurse or follow the target.
        /bin/rm -f "$link" 2>/dev/null || true
        if [[ "${CMUX_CUA_DIAGNOSTICS:-0}" == 1 && ! -L "$link" ]]; then
            printf 'cmux-cua: managed-link-retired path=%q\n' "$link" >&2
        fi
        return 0
    fi
    return 1
}

cmux_cua_skill_link_state() {
    local link="$1"
    if cmux_cua_skill_link_is_managed "$link"; then
        printf '%s' managed
    elif [[ -L "$link" || -e "$link" ]]; then
        printf '%s' user
    else
        printf '%s' missing
    fi
}

cmux_cua_skill_project_candidate_is_collision() {
    local candidate="$1"
    local source_document="$2"
    [[ -f "$candidate" ]] || return 1
    cmux_cua_skill_name_is "$candidate" cmux-cua || return 1
    local candidate_canonical source_canonical
    candidate_canonical="$(cmux_cua_skill_canonical_document "$candidate")" || return 1
    source_canonical="$(cmux_cua_skill_canonical_document "$source_document")" || source_canonical="$source_document"
    [[ "$candidate_canonical" != "$source_canonical" ]]
}

cmux_cua_skill_document_is_user_global() {
    local candidate="$1"
    local provider="$2"
    local home="${HOME:-}"
    local codex_home="${CODEX_HOME:-$home/.codex}"
    local candidate_normalized
    candidate_normalized="$(cmux_cua_skill_lexical_normalize "$candidate" 2>/dev/null)" \
        || candidate_normalized="$candidate"
    local candidate_root_canonical=""
    local candidate_root="${candidate%/cmux-cua/SKILL.md}"
    if [[ -d "$candidate_root" ]]; then
        candidate_root_canonical="$(cd "$candidate_root" 2>/dev/null && pwd -P)"
    fi

    local -a global_roots
    if [[ "$provider" == codex ]]; then
        global_roots=("$home/.agents/skills" "$codex_home/skills")
    else
        global_roots=("$home/.claude/skills")
    fi

    local global_root global_normalized
    for global_root in "${global_roots[@]}"; do
        [[ "$global_root" = /* ]] || continue
        global_normalized="$(cmux_cua_skill_lexical_normalize "$global_root" 2>/dev/null)" \
            || continue
        if [[ "$candidate_normalized" == "$global_normalized/cmux-cua/SKILL.md" ]]; then
            return 0
        fi
        local global_root_canonical=""
        if [[ -d "$global_root" ]]; then
            global_root_canonical="$(cd "$global_root" 2>/dev/null && pwd -P)"
        fi
        [[ -n "$candidate_root_canonical" \
           && "$candidate_root_canonical" == "$global_root_canonical" ]] \
            && return 0
    done
    return 1
}

cmux_cua_skill_project_has_collision() {
    local cwd="$1"
    local provider="$2"
    local source_document="$3"
    [[ "$cwd" = /* ]] || return 1
    local dir
    dir="$(cd "$cwd" 2>/dev/null && pwd -P)" || return 1
    local depth=0
    local candidate
    while [[ "$dir" = /* && $depth -lt 64 ]]; do
        # User-global roots are not project roots. Compare the lexical path
        # before following a candidate symlink so a global link cannot be
        # mistaken for a project collision while walking `~/projects/foo` (or
        # a custom CODEX_HOME nested under another directory).
        if [[ "$provider" == codex ]]; then
            local -a candidates=(
                "$dir/.agents/skills/cmux-cua/SKILL.md"
                "$dir/.codex/skills/cmux-cua/SKILL.md"
            )
            for candidate in "${candidates[@]}"; do
                cmux_cua_skill_document_is_user_global "$candidate" "$provider" && continue
                if cmux_cua_skill_project_candidate_is_collision "$candidate" "$source_document"; then
                    return 0
                fi
            done
        else
            candidate="$dir/.claude/skills/cmux-cua/SKILL.md"
            if ! cmux_cua_skill_document_is_user_global "$candidate" "$provider" \
               && cmux_cua_skill_project_candidate_is_collision "$candidate" "$source_document"; then
                return 0
            fi
        fi

        # Match Codex's project-root boundary: once a repository marker is
        # found, do not inspect unrelated parent checkouts.
        [[ -e "$dir/.git" ]] && break
        [[ "$dir" == "/" ]] && break
        dir="${dir%/*}"
        [[ -n "$dir" ]] || dir=/
        depth=$((depth + 1))
    done
    return 1
}

cmux_cua_skill_remove_legacy_links() {
    local home="$1"
    local provider="$2"
    local codex_home="${CODEX_HOME:-$home/.codex}"
    local root link name
    if [[ "$provider" == codex ]]; then
        for root in "$home/.agents/skills" "$codex_home/skills"; do
            [[ "$root" = /* ]] || continue
            for name in cmux-computer-use codex-cua; do
                link="$root/$name"
                cmux_cua_skill_remove_managed_link "$link" || true
            done
        done
    else
        # Older Claude wrappers wrote the legacy name into Codex's shared root.
        for root in "$home/.claude/skills" "$home/.agents/skills"; do
            [[ "$root" = /* ]] || continue
            for name in cmux-computer-use codex-cua; do
                link="$root/$name"
                cmux_cua_skill_remove_managed_link "$link" || true
            done
        done
    fi
}

cmux_cua_skill_reconcile() {
    local provider="$1"
    local source_dir="$2"
    local cwd="$3"
    local install_requested="$4"
    local home="${HOME:-}"
    [[ "$home" = /* && "$source_dir" = /* ]] || return 1
    local source_document="$source_dir/SKILL.md"
    [[ -f "$source_document" ]] || return 1

    local project_collision=0
    if [[ "$install_requested" == 1 ]] \
       && cmux_cua_skill_project_has_collision "$cwd" "$provider" "$source_document"; then
        project_collision=1
    fi
    cmux_cua_skill_remove_legacy_links "$home" "$provider"

    local skills_root destination state legacy_root legacy_state
    if [[ "$provider" == codex ]]; then
        skills_root="$home/.agents/skills"
        legacy_root="${CODEX_HOME:-$home/.codex}/skills"
    else
        skills_root="$home/.claude/skills"
        legacy_root=""
    fi
    destination="$skills_root/cmux-cua"
    state="$(cmux_cua_skill_link_state "$destination")"
    local user_path_collision=0
    local blocked_path=""
    if [[ "$state" == user ]]; then
        user_path_collision=1
        blocked_path="$destination"
    fi
    if [[ -n "$legacy_root" && "$legacy_root" != "$skills_root" ]]; then
        legacy_state="$(cmux_cua_skill_link_state "$legacy_root/cmux-cua")"
        if [[ "$legacy_state" == user ]]; then
            user_path_collision=1
            [[ -n "$blocked_path" ]] || blocked_path="$legacy_root/cmux-cua"
        fi
    else
        legacy_state=missing
    fi

    if [[ "$install_requested" == 1 && "$user_path_collision" == 1 \
          && "${CMUX_CUA_DIAGNOSTICS:-0}" == 1 ]]; then
        printf 'cmux-cua: skill-install=blocked-user-path path=%q\n' "$blocked_path" >&2
    fi
    if [[ "$install_requested" == 1 && "$project_collision" == 1 \
          && "${CMUX_CUA_DIAGNOSTICS:-0}" == 1 ]]; then
        printf 'cmux-cua: skill-install=blocked-project-collision path=%q\n' "$cwd" >&2
    fi

    if [[ "$install_requested" == 1 \
          && "$project_collision" != 1 \
          && "$user_path_collision" != 1 ]]; then
        /bin/mkdir -p "$skills_root" 2>/dev/null || true
        if [[ "$state" == missing ]]; then
            /bin/ln -s "$source_dir" "$destination" 2>/dev/null || true
        elif [[ "$state" == managed ]]; then
            /bin/ln -sfn "$source_dir" "$destination" 2>/dev/null || true
        fi
    elif [[ "$state" == managed ]]; then
        # This is a per-launch preference, not an install receipt. Without
        # opt-in (or beside a project collision), retire only verified
        # app-managed links. Normal user-installed skills are never removed.
        cmux_cua_skill_remove_managed_link "$destination" || true
    fi
    # The deprecated root must not contribute a second managed discovery path,
    # including when the canonical destination has never been installed.
    if [[ "$legacy_state" == managed ]]; then
        cmux_cua_skill_remove_managed_link "$legacy_root/cmux-cua" || true
    fi
    return 0
}

---
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 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
open. Retry the tool call after onboarding reports both grants.

## Using the tools (agent-facing)

cmux already owns the MCP connection's session identity. Do **not** call
`start_session` / `end_session`, and do not pass a custom `session` argument.
The proxy binds every call to the originating cmux surface so the menu-bar
item, cursor, recording cleanup, and background/focus controls stay attached
to the right agent.

### Codex profile

Codex gets the exact ten-tool Computer Use roster, in order:

`list_apps`, `get_app_state`, `click`, `perform_secondary_action`, `set_value`,
`select_text`, `scroll`, `drag`, `press_key`, `type_text`.

Use it like the built-in Computer Use connector:

1. Call `get_app_state` with the app name, full path, or unambiguous bundle id
   before acting. It launches the app if needed and returns the logical-size
   JPEG screenshot plus the compact accessibility tree.
2. Prefer the current snapshot's string `element_index`; use screenshot-local
   x/y coordinates only as fallback.
3. Use xdotool-style key strings such as `super+l` with `press_key`.
4. Operate controls with visible pointer clicks by default: the branded
   cursor gliding to each button and clicking is the product experience, so
   requests like “click 100 + 105” mean literal button-by-button pointer
   interaction on Calculator's buttons. Reserve `type_text` for entering text
   into text fields (search boxes, forms, editors) — not as a shortcut around
   clicking on-screen controls. Only fall back to a single keyboard sequence
   when the user explicitly asks for speed over visibility or a control has no
   clickable element.
5. Actions return a compact dispatch acknowledgement, not a screenshot or
   accessibility tree. After one or more actions, call `get_app_state` before
   deciding what to do next. The returned screenshot/tree is the authoritative
   verification surface, matching the built-in Computer Use connector.
6. Numeric `element_index` values belong only to the state that displayed them.
   Re-snapshot before using an index that may have been renumbered by a layout
   change (Calculator's **All Clear** removes display nodes, for example).
   Multiple coordinate actions against a stable layout may be issued in one
   host turn; do not batch element-index actions across a state-changing step.

Do not expect native cmux extensions such as `get_window_state`, tokens,
`perform_actions`, cursor controls, diagnostics, recordings, or browser/CDP in
this profile. Their absence is required for Codex schema parity.

### Claude/native cmux profile

Perceive, act in logical groups, then verify:

1. `get_window_state` (pid + window_id) returns the accessibility tree **and** a
   screenshot. Ground on both. Prefer element addressing.
2. Act by element: `click` with `element_token` (or `element_index` + pid +
   window_id) is the robust path. Pixel addressing (`x`,`y`) is the fallback.
3. For a stable, already-snapshotted control set, call `perform_actions` once
   with the ordered `click` / `type_text` / `press_key` / other input steps.
   This reuses the existing element-token cache and visible cursor inside the
   persistent proxy instead of paying one model/MCP round trip and AX scan per
   click. Do not put navigation, modal-opening, or layout-changing actions
   before later control references in the same group; re-snapshot immediately
   after any action that can invalidate those controls.
4. Verify the completed group by re-snapshotting and reading the element
   `value` / screenshot — do not assume actions landed (clicks are never
   helper-verified). Operate on-screen controls with visible pointer clicks by
   default — the gliding branded cursor is the product experience. Use
   `type_text` for entering text into text fields, and fall back to a pure
   keyboard sequence only when the user explicitly prefers speed over
   visibility.

Notes:
- In the native profile, use `list_apps` / `launch_app` / `list_windows` to
  find targets;
  `get_window_state` needs a `window_id` from `list_windows`.
- Catalyst apps (e.g. Calculator) can expose an empty AX tree briefly after
  launch and return spurious AX error codes (-25204) even when the action
  landed — re-snapshot and check the result rather than trusting the code.
- Pixel input is obstruction-checked: if another window covers the target
  point cmux-cua refuses with `background_occluded` naming the occluder
  instead of clicking the wrong window. Retry with `delivery_mode:"foreground"`
  or front the target.

## The branded agent cursor

The agent's pointer shows as the cmux logo gradient (`#12c7f5 → #2d8cff →
#6c5cff`) with a `cmux` label, so it is visually distinct from the user's
cursor. It is configured by env the wrapper injects
(`CMUX_CUA_CURSOR_GRADIENT` / `_BLOOM` / `_LABEL`) and is auto-active while
the helper daemon is driving. It remains visible across normal reasoning gaps
and is removed when the driving session ends or the proxy control connection
closes. Each later action reasserts the cursor directly above the driven
target. If no cursor appears during an action, confirm the MCP config uses the
helper socket, has a stable `CMUX_CUA_DEFAULT_SESSION`, and uses the pinned
  cmux-cua build.

## Finding and focusing the driving session

While an agent is driving, the **cmux Computer Use** menu-bar item projects only
the most recently active live agent session and offers two presentation modes:

- **Focus Computer Use** — bring forward the app the agent is driving and resume
  automatically following new targets.
- **Focus Calling Terminal** — return to the terminal that invoked Computer Use
  and reveal the exact workspace + surface running that agent while automation
  continues in the background.

The helper pins its cursor window directly above the driven target window at
the normal application window level. That keeps the cursor visible on the
target while allowing any app the user places in front of that target to cover
the cursor naturally; presentation mode never promotes it to an always-on-top
layer.

The active target and session ordering come from cmux-cua's per-session state
files under `~/Library/Application Support/cmux/cmux-cua/runtime/<scope>/state/`.

The item hides when there is no live or recent session. Toggle visibility in
Settings → Computer Use.

## Troubleshooting

- **Agent has no computer-use tools** — Settings → Computer Use must be on;
  start a *new* session (tools attach at launch).
- **Clicks do nothing / not permitted** — grant Accessibility to cmux Computer Use.
- **Black/empty screenshots** — grant Screen Recording to cmux Computer Use;
  restart only the helper if its automatic refresh has not completed yet.
- **No menu-bar icon** — needs a live/recent session; check the visibility toggle.
- **Prompts name the main cmux app** — a non-cmux fallback executed the helper
  directly. Stop there and report the failure; the bundled path must use the
  tag-scoped socket with `CMUX_CUA_MCP_FORCE_PROXY=1`.
- **Prompts name CmuxCua** — a stale `/Applications/CmuxCua.app` daemon or a
  standalone helper launch is active. Stop it and reset/remove its TCC entry;
  the bundled path never uses that identity.

## Development

- Engine source: `manaflow-ai/cmux-cua` (`libs/cmux-cua/rust`). cmux consumes
  it via `CMUX_CUA_PINNED_SHA` in `scripts/build-cmux-cua.sh`, which builds,
  lipos, and codesigns the binary plus the nested helper into the app bundle.
- The helper daemon's `CMUX_CUA_EXTERNAL_PERMISSION_FLOW=1` prevents
  agent-supplied `check_permissions {prompt:true}` from bypassing cmux
  onboarding. The wrappers set `CMUX_CUA_MCP_FORCE_PROXY=1` and preserve
  the external-flow contract in the proxy process so protected calls wait for
  cmux's post-verification readiness signal.
  There is no ambient executable override. Both profiles resolve the app-bundled
  `cmux-cua` executable and the tag-scoped helper only; missing ownership fails
  closed instead of running a user-supplied executable.
- If the cmux-owned daemon is unavailable, do **not** invoke `cmux-cua`
  directly through Bash and do not start its default socket. Tell the user to
  open Settings → Computer Use or restart the tagged cmux build, then retry the
  MCP tool after the helper runtime is healthy.
- Never hand-edit `docs/.../cmux-cua/mcp-tools.mdx` in the fork — it is
  generated from the Rust tool descriptions.
- cmux-side UX lives in `Sources/App/ComputerUse*.swift`,
  `Packages/macOS/CmuxSettingsUI/.../Sections/ComputerUseSection.swift`, and the
  two wrappers under `Resources/bin/`.