# Table of Contents - [Cua Documentation](#cua-documentation) - [Vibe Coding MCP | Cua](#vibe-coding-mcp-cua) - [Changelog | Cua](#changelog-cua) - [Known limits | Cua](#known-limits-cua) - [API Reference | Cua](#api-reference-cua) - [CLI Reference | Cua](#cli-reference-cua) - [MCP Tools | Cua](#mcp-tools-cua) - [CLI Reference | Cua](#cli-reference-cua) - [Changelog | Cua](#changelog-cua) - [Changelog | Cua](#changelog-cua) - [SDK Reference | Cua](#sdk-reference-cua) - [Build a Custom Agent | Cua](#build-a-custom-agent-cua) - [Interactive Shell | Cua](#interactive-shell-cua) - [macOS Native Task | Cua](#macos-native-task-cua) - [CLI Reference | Cua](#cli-reference-cua) - [Windows Native Task | Cua](#windows-native-task-cua) - [Cloud Sandbox | Cua](#cloud-sandbox-cua) - [macOS Sandboxes | Cua](#macos-sandboxes-cua) - [Prompting Claude Code with Human Demonstrations | Cua](#prompting-claude-code-with-human-demonstrations-cua) - [Linux Sandboxes | Cua](#linux-sandboxes-cua) - [Set Up a Sandbox | Cua](#set-up-a-sandbox-cua) - [Windows Sandboxes | Cua](#windows-sandboxes-cua) - [Android Sandboxes | Cua](#android-sandboxes-cua) - [What is a Computer-Use Agent? | Cua](#what-is-a-computer-use-agent-cua) - [What is a Desktop Sandbox? | Cua](#what-is-a-desktop-sandbox-cua) - [Custom Images | Cua](#custom-images-cua) - [Generate Tasks with AI | Cua](#generate-tasks-with-ai-cua) - [Using the Cloud CLI | Cua](#using-the-cloud-cli-cua) - [API Reference | Cua](#api-reference-cua) - [MCP Server | Cua](#mcp-server-cua) - [LLM Integrations | Cua](#llm-integrations-cua) - [Create a Universal Task | Cua](#create-a-universal-task-cua) - [Claude Code | Cua](#claude-code-cua) - [Getting Started | Cua](#getting-started-cua) - [Tools | Cua](#tools-cua) - [Configuration | Cua](#configuration-cua) - [Lume CLI Reference | Cua](#lume-cli-reference-cua) - [PDF to Form Automation | Cua](#pdf-to-form-automation-cua) - [Migrating from the Computer SDK | Cua](#migrating-from-the-computer-sdk-cua) - [GUI Grounding with Gemini 3 | Cua](#gui-grounding-with-gemini-3-cua) - [Changelog | Cua](#changelog-cua) - [Installation | Cua](#installation-cua) - [Installation | Cua](#installation-cua) - [Windows App behind VPN | Cua](#windows-app-behind-vpn-cua) - [Client Integrations | Cua](#client-integrations-cua) - [Changelog | Cua](#changelog-cua) - [Post-Event Contact Export | Cua](#post-event-contact-export-cua) - [Usage | Cua](#usage-cua) - [Agent SDK v0.4 API Reference | Cua](#agent-sdk-v0-4-api-reference-cua) - [Agent SDK v0.5 API Reference | Cua](#agent-sdk-v0-5-api-reference-cua) - [Agent SDK v0.6 API Reference | Cua](#agent-sdk-v0-6-api-reference-cua) - [Introduction | Cua](#introduction-cua) - [Agent SDK v0.3 API Reference | Cua](#agent-sdk-v0-3-api-reference-cua) - [Agent SDK v0.7 API Reference | Cua](#agent-sdk-v0-7-api-reference-cua) - [Computer SDK v0.3 API Reference | Cua](#computer-sdk-v0-3-api-reference-cua) - [Quickstart | Cua](#quickstart-cua) - [Installation | Cua](#installation-cua) - [Sandbox Setup | Cua](#sandbox-setup-cua) - [Homebrew Testing | Cua](#homebrew-testing-cua) - [Cua VLM Router | Cua](#cua-vlm-router-cua) - [Installation | Cua](#installation-cua) - [Using the Computer SDK | Cua](#using-the-computer-sdk-cua) - [Introduction | Cua](#introduction-cua) - [Browser Tool | Cua](#browser-tool-cua) - [Comparison | Cua](#comparison-cua) - [Stock Analysis with Numbers | Cua](#stock-analysis-with-numbers-cua) - [Command Reference | Cua](#command-reference-cua) - [Sandbox with MCP | Cua](#sandbox-with-mcp-cua) - [What is Cua? | Cua](#what-is-cua-cua) - [Using the Agent SDK | Cua](#using-the-agent-sdk-cua) - [What is Lume? | Cua](#what-is-lume-cua) - [Vision Language Models | Cua](#vision-language-models-cua) - [Command Reference | Cua](#command-reference-cua) - [Desktop Sandbox | Cua](#desktop-sandbox-cua) - [RL Training with GRPO | Cua](#rl-training-with-grpo-cua) - [Computer SDK v0.5 API Reference | Cua](#computer-sdk-v0-5-api-reference-cua) - [Laminar | Cua](#laminar-cua) - [FAQ | Cua](#faq-cua) - [Computer SDK v0.4 API Reference | Cua](#computer-sdk-v0-4-api-reference-cua) - [Cua CLI API Reference | Cua](#cua-cli-api-reference-cua) - [First Steps | Cua](#first-steps-cua) - [Agent Loops | Cua](#agent-loops-cua) - [Yutori | Cua](#yutori-cua) - [HUD | Cua](#hud-cua) - [OpenClaw Setup | Cua](#openclaw-setup-cua) - [Callbacks | Cua](#callbacks-cua) - [Telemetry | Cua](#telemetry-cua) - [Docker Compose | Cua](#docker-compose-cua) - [Building Lumier | Cua](#building-lumier-cua) - [Interfaces Reference | Cua](#interfaces-reference-cua) - [Installation | Cua](#installation-cua) - [Linux Container | Cua](#linux-container-cua) - [Docker | Cua](#docker-cua) - [VM Management | Cua](#vm-management-cua) - [Demonstration-Guided Skills | Cua](#demonstration-guided-skills-cua) - [Custom Agents | Cua](#custom-agents-cua) - [Configuration | Cua](#configuration-cua) - [Kasm Container | Cua](#kasm-container-cua) - [QEMU Android | Cua](#qemu-android-cua) - [Quickstart | Cua](#quickstart-cua) - [Lumier | Cua](#lumier-cua) - [Adapters | Cua](#adapters-cua) - [HTTP Server | Cua](#http-server-cua) - [QEMU Windows | Cua](#qemu-windows-cua) - [QEMU Container | Cua](#qemu-container-cua) - [Changelog | Cua](#changelog-cua) - [Using the Sandbox SDK | Cua](#using-the-sandbox-sdk-cua) - [macOS Sandbox | Cua](#macos-sandbox-cua) - [Changelog | Cua](#changelog-cua) - [Unattended Setup | Cua](#unattended-setup-cua) - [Composed Models | Cua](#composed-models-cua) - [Interactive Shell | Cua](#interactive-shell-cua) - [OSWorld-Verified | Cua](#osworld-verified-cua) - [Simulated Desktop (Preview) | Cua](#simulated-desktop-preview-cua) - [Agent Traces | Cua](#agent-traces-cua) - [Creating Private Tasks | Cua](#creating-private-tasks-cua) - [QEMU Linux | Cua](#qemu-linux-cua) - [ScreenSpot-v2 | Cua](#screenspot-v2-cua) - [Interactive Tool | Cua](#interactive-tool-cua) - [App Helpers | Cua](#app-helpers-cua) - [XFCE Container | Cua](#xfce-container-cua) - [Chat History | Cua](#chat-history-cua) - [Tunneling | Cua](#tunneling-cua) - [ScreenSpot-Pro | Cua](#screenspot-pro-cua) - [Registry | Cua](#registry-cua) - [Universal GUI | Cua](#universal-gui-cua) - [RL Dataloader | Cua](#rl-dataloader-cua) - [Secrets & Environment Variables | Cua](#secrets-environment-variables-cua) - [Snapshots | Cua](#snapshots-cua) - [Introduction | Cua](#introduction-cua) - [MCP Server | Cua](#mcp-server-cua) - [PiP Preview (Experimental) | Cua](#pip-preview-experimental-cua) - [Base Images | Cua](#base-images-cua) - [Human-in-the-Loop | Cua](#human-in-the-loop-cua) - [Sandbox Lifecycle | Cua](#sandbox-lifecycle-cua) - [Telemetry | Cua](#telemetry-cua) - [VNC Recorder | Cua](#vnc-recorder-cua) - [Prompt Caching | Cua](#prompt-caching-cua) - [Custom Tools | Cua](#custom-tools-cua) - [What is Cua Driver? | Cua](#what-is-cua-driver-cua) - [Trajectories | Cua](#trajectories-cua) - [Parallel Sandboxes | Cua](#parallel-sandboxes-cua) - [Tasks | Cua](#tasks-cua) - [Comparison | Cua](#comparison-cua) - [Integrations | Cua](#integrations-cua) - [Autostart | Cua](#autostart-cua) - [Local Computer Server | Cua](#local-computer-server-cua) - [Images | Cua](#images-cua) - [Linux pre-release | Cua](#linux-pre-release-cua) - [Running Cua Driver under SSH on Windows | Cua](#running-cua-driver-under-ssh-on-windows-cua) - [Updating | Cua](#updating-cua) - [Message Format | Cua](#message-format-cua) - [Tracing API | Cua](#tracing-api-cua) - [MCP process model | Cua](#mcp-process-model-cua) - [Sandboxed Python | Cua](#sandboxed-python-cua) - [Quickstart | Cua](#quickstart-cua) --- # Cua Documentation [Open source13.1k](https://github.com/trycua/cua) Cua Docs ======== Give every agent a cloud desktop. Built for Claude Code, Codex, OpenClaw, and computer-use agents. [Get started](https://cua.ai/docs/cua/guide/get-started/what-is-cua) [Book a call](https://cua.cal.com/f/cua-demo) [Try Cua Cloud](https://cua.ai/) [![Cua Platform](https://cua.ai/docs/img/hero.png)](https://cua.ai/) [### Guide\ \ Set up your first agent, configure sandboxes, and learn the core concepts.\ \ Explore](https://cua.ai/docs/cua/guide/get-started/what-is-cua) [### Examples\ \ Form filling, contact export, VPN automation, and more — ready to copy and run.\ \ Explore](https://cua.ai/docs/cua/examples/automation/form-filling) [### API Reference\ \ Sandbox, Agent, and Cloud SDK — every class, method, and parameter.\ \ Explore](https://cua.ai/docs/cua/reference/sandbox-sdk) [### Cloud\ \ Managed sandboxes for production. Deploy agents at scale without managing infra.\ \ Explore](https://cua.ai/) Featured Examples ----------------- From form filling to VPN automation [View all](https://cua.ai/docs/cua/examples/automation/form-filling) [### Windows App Behind VPN\ \ Automate legacy Windows applications securely behind VPN](https://cua.ai/docs/cua/examples/platform-specific/windows-app-behind-vpn) [### PDF to Form Automation\ \ Enhance interactions between form filling and local file systems](https://cua.ai/docs/cua/examples/automation/form-filling) [### Contact Export\ \ Export contacts from post-event platforms automatically](https://cua.ai/docs/cua/examples/automation/post-event-contact-export) [### Complex UI Navigation\ \ Navigate complex UIs with Gemini vision capabilities](https://cua.ai/docs/cua/examples/ai-models/gemini-complex-ui-navigation) [View all examples](https://cua.ai/docs/cua/examples/automation/form-filling) Ready to build? --------------- Go from zero to a running agent in under five minutes. [Get started](https://cua.ai/docs/cua/guide/get-started/what-is-cua) [API Reference](https://cua.ai/docs/cua/reference/sandbox-sdk) This site uses cookies for website functionality, analytics, and personalized content. Okay --- # Vibe Coding MCP | Cua Cua Vibe Coding MCP =============== Connect your AI agents to Cua documentation and source code The Cua MCP server equips AI coding agents with deep knowledge about Cua's APIs, patterns, source code, and best practices. When connected to your development environment, it enables AI assistants to: * **Search documentation** with full-text and semantic search * **Explore source code** across all versions and components * **Generate accurate code** with context from the actual codebase * **Understand Cua internals** by querying versioned implementations [Server URL](https://cua.ai/docs/cua/vibe-coding-mcp#server-url) ----------------------------------------------------------------- | Endpoint | URL | | --- | --- | | Streamable HTTP Transport | `https://vk-mcp.cua.ai/mcp` | [Available Tools](https://cua.ai/docs/cua/vibe-coding-mcp#available-tools) --------------------------------------------------------------------------- The MCP server exposes four read-only query tools: ### [Documentation Tools](https://cua.ai/docs/cua/vibe-coding-mcp#documentation-tools) | Tool | Description | | --- | --- | | `query_docs_db` | SQL queries against documentation (FTS5 full-text search) | | `query_docs_vectors` | Semantic vector search for natural language queries | ### [Code Search Tools](https://cua.ai/docs/cua/vibe-coding-mcp#code-search-tools) | Tool | Description | | --- | --- | | `query_code_db` | SQL queries against versioned source code (FTS5 full-text search) | | `query_code_vectors` | Semantic code search across all components and versions | [Connect Your AI Tools](https://cua.ai/docs/cua/vibe-coding-mcp#connect-your-ai-tools) --------------------------------------------------------------------------------------- ### [Cursor](https://cua.ai/docs/cua/vibe-coding-mcp#cursor) 1. Press `Shift+Command+J` (Mac) or `Shift+Ctrl+J` (Windows/Linux) to open settings 2. Find "MCP Tools" in the left sidebar 3. Click "Add Custom MCP" to open `mcp.json` 4. Add the Cua MCP server configuration: { "mcpServers": { "Cua MCP": { "url": "https://vk-mcp.cua.ai/mcp" } } } ### [Claude Code](https://cua.ai/docs/cua/vibe-coding-mcp#claude-code) Add the MCP server using the CLI: claude mcp add --transport http cua-mcp https://vk-mcp.cua.ai/mcp Verify the connection: claude mcp list Expected output: Checking MCP server health... cua-mcp: https://vk-mcp.cua.ai/mcp (HTTP) - ✓ Connected Management commands: # View server details claude mcp get cua-mcp # Remove server if needed claude mcp remove cua-mcp -s local ### [Claude Web / Claude Desktop](https://cua.ai/docs/cua/vibe-coding-mcp#claude-web--claude-desktop) 1. Go to **Settings** > **Connectors** 2. Click **Add custom connector** 3. Enter the following: * **Name**: `Cua MCP` * **URL**: `https://vk-mcp.cua.ai/mcp` 4. Click **Add** ### [Windsurf](https://cua.ai/docs/cua/vibe-coding-mcp#windsurf) 1. Open Windsurf Settings (bottom right settings button) 2. Navigate to **Cascade** > **Model Context Protocol** 3. Click **Add Server** > **Add custom server** 4. Select **Streamable HTTP** transport and enter: `https://vk-mcp.cua.ai/mcp` Configuration file location: * **macOS**: `~/.codeium/windsurf/mcp_config.json` * **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json` * **Linux**: `~/.codeium/windsurf/mcp_config.json` ### [Cline (VS Code)](https://cua.ai/docs/cua/vibe-coding-mcp#cline-vs-code) 1. Open the Cline extension panel in VS Code 2. Click the menu (⋮) in the top right 3. Select **MCP Servers** 4. Click **Remote Servers** tab 5. Enter: * **Server Name**: `Cua MCP` * **Server URL**: `https://vk-mcp.cua.ai/mcp` 6. Click **Add Server** ### [GitHub Copilot](https://cua.ai/docs/cua/vibe-coding-mcp#github-copilot) 1. Enable MCP in VS Code: Settings > search "MCP" > enable `chat.mcp.enabled` 2. Create `.vscode/mcp.json` in your project: { "servers": { "Cua MCP": { "url": "https://vk-mcp.cua.ai/mcp" } } } 3. Open Copilot Chat, switch to **Agent mode**, and the tools will be available ### [Other MCP-Compatible Tools](https://cua.ai/docs/cua/vibe-coding-mcp#other-mcp-compatible-tools) For any MCP-compatible application: **Streamable HTTP Connection**: https://vk-mcp.cua.ai/mcp **Common JSON Configuration**: { "servers": { "Cua MCP": { "url": "https://vk-mcp.cua.ai/mcp" } } } Was this page helpful? YesNo * * * ### On this page [Server URL](https://cua.ai/docs/cua/vibe-coding-mcp#server-url) [Available Tools](https://cua.ai/docs/cua/vibe-coding-mcp#available-tools) [Documentation Tools](https://cua.ai/docs/cua/vibe-coding-mcp#documentation-tools) [Code Search Tools](https://cua.ai/docs/cua/vibe-coding-mcp#code-search-tools) [Connect Your AI Tools](https://cua.ai/docs/cua/vibe-coding-mcp#connect-your-ai-tools) [Cursor](https://cua.ai/docs/cua/vibe-coding-mcp#cursor) [Claude Code](https://cua.ai/docs/cua/vibe-coding-mcp#claude-code) [Claude Web / Claude Desktop](https://cua.ai/docs/cua/vibe-coding-mcp#claude-web--claude-desktop) [Windsurf](https://cua.ai/docs/cua/vibe-coding-mcp#windsurf) [Cline (VS Code)](https://cua.ai/docs/cua/vibe-coding-mcp#cline-vs-code) [GitHub Copilot](https://cua.ai/docs/cua/vibe-coding-mcp#github-copilot) [Other MCP-Compatible Tools](https://cua.ai/docs/cua/vibe-coding-mcp#other-mcp-compatible-tools) Copy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude --- # Changelog | Cua Cua DriverReference Changelog ========= Release history for cua-driver [cua-driver Changelog](https://cua.ai/docs/cua-driver/reference/changelog#cua-driver-changelog) ================================================================================================ All notable changes to cua-driver are documented here. These are the `cua-driver-rs` (Rust port) releases. The Rust port ships the same user-facing `cua-driver` binary for macOS and Windows, plus Linux pre-release artifacts for early testing. All versions are currently published as GitHub **prereleases** under the `cua-driver-rs-v*` tag prefix (distinct from the Swift driver's `cua-driver-v*` tags so their artifacts don't collide). The canonical, always-current source is the [GitHub releases page](https://github.com/trycua/cua/releases) . Each GitHub release body is auto-generated per release from the commits touching `libs/cua-driver/rust`, including SHA256 checksums and install instructions. [0.5.1 (2026-06-01)](https://cua.ai/docs/cua-driver/reference/changelog#051-2026-06-01) ---------------------------------------------------------------------------------------- * **Install home unified on `~/.cua-driver` + collision fix.** The release installer (`install.sh` → `_install-rust.sh`) was still defaulting its package home to the legacy `~/.cua-driver-rs`, while the local installer (`install-local.sh`) and the runtime already used `~/.cua-driver` (renamed in v0.2.16). That mismatch meant a machine could end up with two homes and two conflicting installs. The release installer now defaults to `~/.cua-driver` (still honoring the `CUA_DRIVER_RS_HOME` override), and on every install it (a) cleans up a prior `install-local` dev build under the shared home — stops the daemon, removes the `*-local-*` release dirs and the local signing-identity marker — and (b) sweeps a stale `~/.cua-driver-rs` left by an older release. Both steps are best-effort, idempotent, and conservative (marker-gated; they never touch a real release dir, the `current` symlink, or unrelated user state). TCC grants are preserved — the `/Applications/CuaDriver.app` bundle is replaced in place, not `tccutil reset`. The Windows installer (`install.ps1`) already used `~/.cua-driver` and migrated the legacy home, so it is unchanged. [0.5.0 (2026-06-01)](https://cua.ai/docs/cua-driver/reference/changelog#050-2026-06-01) ---------------------------------------------------------------------------------------- * **Windows: per-session agent cursors** — the per-session cursor model (macOS #1779) is ported to Windows, so concurrent sessions are tracked per-session on Windows too (#1801). * **Streamable-HTTP MCP transport (parallel multi-agent).** Over stdio, one `cua-driver mcp` process is a single pipe, so a client's tool calls — including multiple subagents — serialize. The daemon itself is concurrent. Set `CUA_DRIVER_RS_MCP_HTTP_PORT=` and the daemon also serves MCP over HTTP (`POST http://127.0.0.1:/mcp`, loopback only), so each agent opens its **own** connection and they run truly in parallel — measured 3.6× on 10 concurrent calls. Per-connection ordering keeps a single agent's sequence correct; the per-`(pid, window_id)` cache + per-session cursor make concurrent cross-connection actions safe. `move_cursor` is now `readOnlyHint:true` so MCP clients also parallelize cursor moves on stdio (mutating tools stay serialized on purpose) (#1799). * **Breaking — session identity is now caller-declared.** A "session" (which owns the agent cursor + per-session state) used to be minted per MCP connection, so it couldn't be set from the CLI and couldn't span a run that touches multiple apps. It's now an explicit identity you declare: pass a `session` id (or call the new `start_session`/`end_session` tools), and the same id drives the same cursor over MCP, the CLI, or the raw socket, following the run across any apps/windows. **The cursor is now opt-in:** a run shows a cursor only when it declares a `session` — anonymous calls execute without one. Sessions are reclaimed by `end_session` or an idle-TTL (default 300s, override `CUA_DRIVER_RS_SESSION_IDLE_TTL_SECS`) instead of connection-EOF. Per-session config + recording keep their existing connection-scoped cleanup as a fallback when no `session` is declared. Update agents to `start_session` at the start of a run (the bundled skill + MCP instructions now say so). * macOS: fix a daemon crash (`EXC_BREAKPOINT` in `AXUIElementCopyActionNames`) when two sessions drive the same window concurrently. Element actions (`click`, `type_text`, `set_value`, …) read the target `AXUIElementRef` out of the per-`(pid, window_id)` cache, but a concurrent `get_window_state` could replace that cache entry and `CFRelease` the element to zero while the action was still using it — a use-after-free. The cache now hands out a retained guard (`CFRetain` under the cache lock, `CFRelease` on drop), so an in-flight action keeps the element alive across a concurrent refresh. * macOS (local dev install only): `install-local.sh` now clears a stale TCC grant left over from a previous signing identity. If you first granted Accessibility / Screen Recording while the bundle was ad-hoc signed, that grant was pinned to the per-build `cdhash` and silently stopped matching on the next rebuild — the daemon read `NOT granted` while System Settings still showed CuaDriver toggled ON, a dead end re-toggling couldn't fix. The installer records the signing identity and, when it changes, runs `tccutil reset` so the next grant re-pins cleanly to the stable self-signed certificate (after which grants survive all future rebuilds). Release builds are unaffected — they're CI-signed with a stable identity (#1792 follow-up). [0.4.3 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#043-2026-05-31) ---------------------------------------------------------------------------------------- * macOS: the agent-cursor overlay now actually renders in the `serve` daemon. It was only wired into the in-process `mcp` path, so in the daemon-proxy setup (the default) every cursor command was a silent no-op and the agent cursor never appeared (#1790). * macOS: `cua-driver permissions grant` no longer spams the TCC prompt — it raises a single dialog and then polls silently, and the gate honours its deadline instead of re-prompting (and restarting the daemon) on every ~25s re-exec (#1791). * Dev: `install-local` now signs the bundle with a stable self-signed identity, so TCC grants (Accessibility / Screen Recording) survive rebuilds instead of resetting on every install (#1792). [0.4.2 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#042-2026-05-31) ---------------------------------------------------------------------------------------- * macOS: guard the SkyLight auth-message selector on macOS 14 Sonoma so the driver no longer crashes on launch (#1782, #1503). * macOS: enable Chromium/Electron accessibility trees via `AXManualAccessibility`, so `get_window_state` can see their window content (#1756). [0.4.1 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#041-2026-05-31) ---------------------------------------------------------------------------------------- * macOS: per-session agent cursors, so concurrent sessions each get their own visual agent cursor (#1779). * macOS: ship `AppIcon.icns` in the bundle so `CuaDriver.app` no longer shows a blank icon (#1780, #1496). * macOS: guard AppKit initialization so `mcp` runs headless instead of SIGABRT-ing (#1781, #1724). [0.4.0 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#040-2026-05-31) ---------------------------------------------------------------------------------------- * Daemon session-identity model: the daemon now owns and cleans up session-scoped recording and config, tying that state to the session that created it (#1776). [0.3.6 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#036-2026-05-30) ---------------------------------------------------------------------------------------- * macOS: fix permissions status so it reports the driver's real TCC grants (via the daemon) instead of the calling terminal's — it no longer claims granted when only the caller holds the grant (#1774). [0.3.5 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#035-2026-05-30) ---------------------------------------------------------------------------------------- * macOS: bind the `serve` socket before the permissions gate, so clients can connect even while permissions are still being resolved (#1761, #1773). [0.3.4 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#034-2026-05-30) ---------------------------------------------------------------------------------------- * Maintenance release (no path-specific changes). [0.3.3 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#033-2026-05-30) ---------------------------------------------------------------------------------------- * Maintenance release (no path-specific changes). [0.3.2 (2026-05-27)](https://cua.ai/docs/cua-driver/reference/changelog#032-2026-05-27) ---------------------------------------------------------------------------------------- * Add a `check-update` CLI verb and a `check_for_update` MCP tool so clients can detect when a newer driver is available (#1734). [0.3.1 (2026-05-27)](https://cua.ai/docs/cua-driver/reference/changelog#031-2026-05-27) ---------------------------------------------------------------------------------------- * First release in the 0.3.x line, which began the macOS TCC / permissions hardening series. [0.2.x (2026-05-17 – 2026-05-21)](https://cua.ai/docs/cua-driver/reference/changelog#02x-2026-05-17--2026-05-21) ----------------------------------------------------------------------------------------------------------------- * Pre-release iteration on the Rust port across versions 0.2.0–0.2.18, including cross-platform build and packaging work for the macOS, Windows, and Linux pre-release artifacts. [0.1.x (2026-05-14)](https://cua.ai/docs/cua-driver/reference/changelog#01x-2026-05-14) ---------------------------------------------------------------------------------------- * Initial `cua-driver-rs` pre-releases. See the [GitHub releases](https://github.com/trycua/cua/releases) for details. Was this page helpful? YesNo [Known limits\ \ What Cua Driver can't do, and the workarounds](https://cua.ai/docs/cua-driver/reference/limits) [Introduction\ \ Next Page](https://cua.ai/docs/cua/guide) * * * ### On this page [cua-driver Changelog](https://cua.ai/docs/cua-driver/reference/changelog#cua-driver-changelog) [0.5.1 (2026-06-01)](https://cua.ai/docs/cua-driver/reference/changelog#051-2026-06-01) [0.5.0 (2026-06-01)](https://cua.ai/docs/cua-driver/reference/changelog#050-2026-06-01) [0.4.3 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#043-2026-05-31) [0.4.2 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#042-2026-05-31) [0.4.1 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#041-2026-05-31) [0.4.0 (2026-05-31)](https://cua.ai/docs/cua-driver/reference/changelog#040-2026-05-31) [0.3.6 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#036-2026-05-30) [0.3.5 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#035-2026-05-30) [0.3.4 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#034-2026-05-30) [0.3.3 (2026-05-30)](https://cua.ai/docs/cua-driver/reference/changelog#033-2026-05-30) [0.3.2 (2026-05-27)](https://cua.ai/docs/cua-driver/reference/changelog#032-2026-05-27) [0.3.1 (2026-05-27)](https://cua.ai/docs/cua-driver/reference/changelog#031-2026-05-27) [0.2.x (2026-05-17 – 2026-05-21)](https://cua.ai/docs/cua-driver/reference/changelog#02x-2026-05-17--2026-05-21) [0.1.x (2026-05-14)](https://cua.ai/docs/cua-driver/reference/changelog#01x-2026-05-14) Copy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude --- # Known limits | Cua Cua DriverReference Known limits ============ What Cua Driver can't do, and the workarounds Cua Driver's no-foreground contract holds for every app the driver reaches via AX or via the SkyLight-routed pixel click. Four categories of target fall outside that envelope. Each is documented here with the workaround. [Chromium coerces synthetic right-clicks on web content](https://cua.ai/docs/cua-driver/reference/limits#chromium-coerces-synthetic-right-clicks-on-web-content) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- **Symptom:** `right_click({pid, x, y})` on a Chrome, Edge, Brave, or Arc tab's web content fires a left-click instead of opening the context menu. **Cause:** Chromium's renderer-IPC filter drops the right-click subtype bit on events that don't come through the HID tap. Every synthesized-event path on macOS hits this wall, not just ours. **Workarounds, in order of preference:** 1. Use `right_click({pid, element_index})` on AX-addressable targets (links, buttons, toolbar items). AX dispatch sidesteps the renderer filter entirely. 2. For context menus on pure web content (nothing in the AX tree), activate Chrome briefly and fall back to a HID-tap right-click. Breaks the no-foreground-steal promise for that one click. Element-indexed right-click (`right_click({(pid, element_index)})`) works fine. The limit is specifically pixel right-click on non-AX Chromium web content. [Canvas apps need brief frontmost activation](https://cua.ai/docs/cua-driver/reference/limits#canvas-apps-need-brief-frontmost-activation) ------------------------------------------------------------------------------------------------------------------------------------------- **Affected:** Blender (GHOST event source), Unity editor / Unity games, most native games, some WebGL-heavy Electron apps. **Symptom:** `click({pid, x, y})` on a Blender viewport silently no-ops. `launch_app` works, the window is visible, the tree says nothing actionable is there. Clicks vanish. **Cause:** These apps only accept events from `cghidEventTap` with a leading `mouseMoved`. They explicitly filter out per-pid-routed events, which is the path Cua Driver uses for its backgrounded dispatch. There's no per-pid recipe that reaches them. **Workaround:** The driver auto-detects these targets and falls back to a brief activation + HID-tap click. The cursor visibly warps. The activation is the shortest possible and the click fires within the same event loop turn, so focus returns to the user's previous app within a frame or two, but the warp is noticeable. If you're automating Blender or a game, the no-foreground-steal contract does not apply. The driver will tell you: the `click` response includes `dispatch: "hid_tap"` when the HID fallback fired. [Off-Space SwiftUI windows strip their AX tree](https://cua.ai/docs/cua-driver/reference/limits#off-space-swiftui-windows-strip-their-ax-tree) ----------------------------------------------------------------------------------------------------------------------------------------------- **Symptom:** `get_window_state({pid, window_id})` on a window that's on a different Space (e.g. System Settings parked on Space 2 while you're on Space 1) returns a tiny tree that only contains the menu bar, or just the AXApplication root. **Cause:** macOS 14+ strips AX detail from non-current-Space SwiftUI windows as a privacy / performance tradeoff. AppKit apps are not affected. This is an Apple design decision; no workaround exists that keeps the window off-Space. **Response shape:** Cua Driver surfaces this explicitly. Every `get_window_state` response on an off-current-Space window carries `off_space: true` plus the `window_space_ids` array, so callers can decide to switch Space, pick a different window, or skip the turn. **Workarounds:** 1. Switch the user to the target's Space first (`SpaceMigrator.migrate`, exposed via the forthcoming `migrate_space` tool). Breaks the no-Space-bounce promise. 2. Target an AppKit equivalent of the app if one exists. 3. Limit off-Space automation to AppKit apps where the tree stays populated. [Minimized windows silently drop keyboard commits](https://cua.ai/docs/cua-driver/reference/limits#minimized-windows-silently-drop-keyboard-commits) ----------------------------------------------------------------------------------------------------------------------------------------------------- **Symptom:** `press_key({pid, element_index, key: "return"})` on a text field in a minimized window returns success, but the field doesn't commit. You hear the macOS system-alert beep, or nothing happens. **Cause:** AX reads and AX-dispatched clicks propagate through to minimized windows normally, but keyboard-commit events (Return, Space, Tab) require renderer focus, which AX focus does not confer on a minimized window. This is a macOS-wide behavior; every automation tool hits it. **Workarounds:** 1. Use `set_value({pid, element_index, value: "..."})` to write the field's value directly. No keyboard event involved; no focus handoff required. 2. AX-click a commit-equivalent button (Go, Submit, Send, OK) rather than relying on Return. 3. Un-minimize the window (`hotkey({pid, keys: ["cmd", "m"]})` or click the Dock icon). Breaks the background contract for that window. `set_value` is the right answer 90% of the time. It sidesteps both the minimized-focus issue and the general "which event commits this field" ambiguity. [Permission boundaries](https://cua.ai/docs/cua-driver/reference/limits#permission-boundaries) ----------------------------------------------------------------------------------------------- Cua Driver is constrained by the usual macOS permission model. Two relevant grants: * **Accessibility** (System Settings → Privacy & Security → Accessibility) is required for every AX read, every element-indexed click, every keyboard / text primitive. Without it, `check_permissions` returns `accessibility: false` and every tool returns a structured error. * **Screen Recording** is required for screenshots and for the `som` / `vision` capture modes. Without it, `get_window_state` in those modes returns a tree but no PNG; pure `ax` mode still works. Grants are tied to the `CuaDriver.app` bundle identity. Rebuilding Cua Driver from source preserves the grants because `build-app.sh` pins a stable bundle id (`com.trycua.driver`). See [Installation](https://cua.ai/docs/cua-driver/guide/getting-started/installation) for the grant flow. Was this page helpful? YesNo [MCP Tools\ \ Reference for every MCP tool Cua Driver exposes](https://cua.ai/docs/cua-driver/reference/mcp-tools) [Changelog\ \ Release history for cua-driver](https://cua.ai/docs/cua-driver/reference/changelog) * * * ### On this page [Chromium coerces synthetic right-clicks on web content](https://cua.ai/docs/cua-driver/reference/limits#chromium-coerces-synthetic-right-clicks-on-web-content) [Canvas apps need brief frontmost activation](https://cua.ai/docs/cua-driver/reference/limits#canvas-apps-need-brief-frontmost-activation) [Off-Space SwiftUI windows strip their AX tree](https://cua.ai/docs/cua-driver/reference/limits#off-space-swiftui-windows-strip-their-ax-tree) [Minimized windows silently drop keyboard commits](https://cua.ai/docs/cua-driver/reference/limits#minimized-windows-silently-drop-keyboard-commits) [Permission boundaries](https://cua.ai/docs/cua-driver/reference/limits#permission-boundaries) Copy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude --- # API Reference | Cua API Reference ============= TypeScript API reference for the Cua-Bot sandboxed agent framework v1.0.14npm install -g cuabot * * * [client](https://cua.ai/docs/cuabot/reference#client) ------------------------------------------------------ CuaBot Server Client Connects to the CuaBot server via HTTP ### [CuaBotClient](https://cua.ai/docs/cuabot/reference#cuabotclient) #### [Constructor](https://cua.ai/docs/cuabot/reference#constructor) new CuaBotClient(port: number) **Parameters:** | Name | Type | Description | | --- | --- | --- | | `port` | `number` | | #### [Methods](https://cua.ai/docs/cuabot/reference#methods) ##### [CuaBotClient.for](https://cua.ai/docs/cuabot/reference#cuabotclientfor) for(): Promise< **Returns:** `Promise<` ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest) request(): Promise **Returns:** `Promise<number | null>` ##### [CuaBotClient.status](https://cua.ai/docs/cuabot/reference#cuabotclientstatus) status(): Promise< **Returns:** `Promise<` ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-1) request(): Promise **Returns:** `Promise<string>` ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-2) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-3) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-4) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-5) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-6) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-7) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-8) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-9) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-10) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-11) request(): Promise ##### [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-12) request(): Promise ### [setSessionName](https://cua.ai/docs/cuabot/reference#setsessionname) function setSessionName(name: string | null): void **Parameters:** | Name | Type | Description | | --- | --- | --- | | `name` | \`string | null\` | ### [getSessionName](https://cua.ai/docs/cuabot/reference#getsessionname) function getSessionName(): string | null **Returns:** `string | null` ### [isServerRunning](https://cua.ai/docs/cuabot/reference#isserverrunning) async function isServerRunning(): Promise< **Returns:** `Promise<` ### [ensureServerRunning](https://cua.ai/docs/cuabot/reference#ensureserverrunning) async function ensureServerRunning(): Promise **Returns:** `Promise<number>` * * * [settings](https://cua.ai/docs/cuabot/reference#settings) ---------------------------------------------------------- CuaBot Settings Management ### [Settings](https://cua.ai/docs/cuabot/reference#settings-1) interface Settings { defaultAgent?: string; telemetryEnabled?: boolean; aliasIgnored?: boolean; } | Property | Type | Description | | --- | --- | --- | | `defaultAgent` | `string` | _(optional)_ | | `telemetryEnabled` | `boolean` | _(optional)_ | | `aliasIgnored` | `boolean` | _(optional)_ | ### [AGENTS](https://cua.ai/docs/cuabot/reference#agents) const AGENTS: const ### [loadSettings](https://cua.ai/docs/cuabot/reference#loadsettings) function loadSettings(): Settings **Returns:** `Settings` ### [saveSettings](https://cua.ai/docs/cuabot/reference#savesettings) function saveSettings(settings: Settings): void **Parameters:** | Name | Type | Description | | --- | --- | --- | | `settings` | `Settings` | | ### [getDefaultAgent](https://cua.ai/docs/cuabot/reference#getdefaultagent) function getDefaultAgent(): string | undefined **Returns:** `string | undefined` ### [setDefaultAgent](https://cua.ai/docs/cuabot/reference#setdefaultagent) function setDefaultAgent(agent: string): void **Parameters:** | Name | Type | Description | | --- | --- | --- | | `agent` | `string` | | ### [getTelemetryEnabled](https://cua.ai/docs/cuabot/reference#gettelemetryenabled) function getTelemetryEnabled(): boolean **Returns:** `boolean` ### [isTelemetryConfigured](https://cua.ai/docs/cuabot/reference#istelemetryconfigured) function isTelemetryConfigured(): boolean **Returns:** `boolean` ### [setTelemetryEnabled](https://cua.ai/docs/cuabot/reference#settelemetryenabled) function setTelemetryEnabled(enabled: boolean): void **Parameters:** | Name | Type | Description | | --- | --- | --- | | `enabled` | `boolean` | | ### [getAliasIgnored](https://cua.ai/docs/cuabot/reference#getaliasignored) function getAliasIgnored(): boolean **Returns:** `boolean` ### [setAliasIgnored](https://cua.ai/docs/cuabot/reference#setaliasignored) function setAliasIgnored(ignored: boolean): void **Parameters:** | Name | Type | Description | | --- | --- | --- | | `ignored` | `boolean` | | Was this page helpful? YesNo [Installation\ \ Install Cua-Bot and its dependencies](https://cua.ai/docs/cuabot/guide/getting-started/installation) [Changelog\ \ Release history for Cua-Bot](https://cua.ai/docs/cuabot/reference/changelog) * * * ### On this page [client](https://cua.ai/docs/cuabot/reference#client) [CuaBotClient](https://cua.ai/docs/cuabot/reference#cuabotclient) [Constructor](https://cua.ai/docs/cuabot/reference#constructor) [Methods](https://cua.ai/docs/cuabot/reference#methods) [CuaBotClient.for](https://cua.ai/docs/cuabot/reference#cuabotclientfor) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest) [CuaBotClient.status](https://cua.ai/docs/cuabot/reference#cuabotclientstatus) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-1) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-2) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-3) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-4) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-5) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-6) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-7) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-8) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-9) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-10) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-11) [CuaBotClient.request](https://cua.ai/docs/cuabot/reference#cuabotclientrequest-12) [setSessionName](https://cua.ai/docs/cuabot/reference#setsessionname) [getSessionName](https://cua.ai/docs/cuabot/reference#getsessionname) [isServerRunning](https://cua.ai/docs/cuabot/reference#isserverrunning) [ensureServerRunning](https://cua.ai/docs/cuabot/reference#ensureserverrunning) [settings](https://cua.ai/docs/cuabot/reference#settings) [Settings](https://cua.ai/docs/cuabot/reference#settings-1) [AGENTS](https://cua.ai/docs/cuabot/reference#agents) [loadSettings](https://cua.ai/docs/cuabot/reference#loadsettings) [saveSettings](https://cua.ai/docs/cuabot/reference#savesettings) [getDefaultAgent](https://cua.ai/docs/cuabot/reference#getdefaultagent) [setDefaultAgent](https://cua.ai/docs/cuabot/reference#setdefaultagent) [getTelemetryEnabled](https://cua.ai/docs/cuabot/reference#gettelemetryenabled) [isTelemetryConfigured](https://cua.ai/docs/cuabot/reference#istelemetryconfigured) [setTelemetryEnabled](https://cua.ai/docs/cuabot/reference#settelemetryenabled) [getAliasIgnored](https://cua.ai/docs/cuabot/reference#getaliasignored) [setAliasIgnored](https://cua.ai/docs/cuabot/reference#setaliasignored) Copy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude --- # CLI Reference | Cua Cua DriverReference CLI Reference ============= Command Line Interface reference for Cua Driver v0.3.2curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash Cross-platform computer-use automation driver. [Tool dispatch](https://cua.ai/docs/cua-driver/reference/cli-reference#tool-dispatch) -------------------------------------------------------------------------------------- ### [cua-driver list-tools](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-list-tools) List every registered MCP tool with a one-line description. ### [cua-driver describe](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-describe) Print a tool's full description and JSON input schema. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Name of the MCP tool to describe. | ### [cua-driver call](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-call) Invoke an MCP tool directly from the shell. Runs the same handler the MCP server uses. JSON arguments may be passed as a positional JSON object or through stdin. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Name of the MCP tool to invoke. | | `` | String | No | JSON object for the tool input schema. If omitted, stdin is read when piped. | **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--screenshot-out-file` | String | — | Write the first image content block from the response to this path. | | `--socket` | String | — | Override the daemon socket or named-pipe path. | [Daemon management](https://cua.ai/docs/cua-driver/reference/cli-reference#daemon-management) ---------------------------------------------------------------------------------------------- ### [cua-driver mcp](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-mcp) Run the stdio MCP server. On macOS, shell-spawned MCP processes can auto-launch and proxy through a CuaDriver.app daemon so TCC grants attach to the bundle. On Windows and Linux, MCP proxies through an already-running daemon when one is listening. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path used by the proxy fallback. | **Flags:** | Name | Description | | --- | --- | | `--no-daemon-relaunch` | Stay in-process instead of proxying through a daemon. | | `--claude-code-computer-use-compat` | Expose the Claude Code computer-use compatibility screenshot surface. | ### [cua-driver serve](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-serve) Run Cua Driver as a long-running daemon. The daemon owns per-process state such as element-index caches, recording state, and cursor overlay state. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path. | | `--pid-file` | String | — | Override the pid-file path on Unix targets. | **Flags:** | Name | Description | | --- | --- | | `--no-permissions-gate` | Skip the macOS first-launch permissions gate. | ### [cua-driver stop](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-stop) Ask the running daemon to exit gracefully. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path. | ### [cua-driver status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-status) Report whether a Cua Driver daemon is running. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path. | | `--pid-file` | String | — | Override the pid-file path on Unix targets. | ### [cua-driver mcp-config](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-mcp-config) Print MCP server config or a client-specific install command. Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, and pi. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--client` | String | — | Client name to print configuration for. | [Trajectory recording](https://cua.ai/docs/cua-driver/reference/cli-reference#trajectory-recording) ---------------------------------------------------------------------------------------------------- ### [cua-driver recording](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording) Control trajectory recording on a running daemon. Recording state lives in-process, so use a daemon for multi-call sessions. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path. | #### [cua-driver recording start](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-start) Start trajectory recording to a directory. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Directory to write turn folders into. | #### [cua-driver recording stop](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-stop) Stop trajectory recording. #### [cua-driver recording status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-status) Print the current recording state. #### [cua-driver recording render](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-render) Render a recorded trajectory directory to an MP4. This pure file-to-file path does not require a running daemon. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Trajectory directory containing recorded turn folders. | | `` | String | Yes | Output MP4 path. | **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--scale` | Number | — | Scale factor for rendered frames. | **Flags:** | Name | Description | | --- | --- | | `--no-zoom` | Disable cursor/action zoom effects in the rendered video. | [Configuration](https://cua.ai/docs/cua-driver/reference/cli-reference#configuration) -------------------------------------------------------------------------------------- ### [cua-driver config](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config) Read or mutate persistent driver configuration. Without a subcommand, prints the full config. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--socket` | String | — | Override the daemon socket or named-pipe path. | #### [cua-driver config show](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-show) Print the full config. #### [cua-driver config get](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-get) Print one config key. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Config key to read. | #### [cua-driver config set](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-set) Set one config key. **Arguments:** | Name | Type | Required | Description | | --- | --- | --- | --- | | `` | String | Yes | Config key to write. | | `` | String | Yes | Value to store. | #### [cua-driver config reset](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-reset) Reset config to defaults. [Diagnostics](https://cua.ai/docs/cua-driver/reference/cli-reference#diagnostics) ---------------------------------------------------------------------------------- ### [cua-driver check-update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-check-update) Check whether a newer cua-driver release is available. Read-only. Uses the same update-state payload as the check\_for\_update MCP tool. **Flags:** | Name | Description | | --- | --- | | `--json` | Emit a machine-readable JSON payload. | | `--no-cache` | Skip the 20-hour on-disk cache and force a GitHub request. | ### [cua-driver update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-update) Check for an update and optionally apply it. The apply path delegates to the canonical platform installer scripts. **Flags:** | Name | Description | | --- | --- | | `--apply` | Download and install the latest release when one is available. | | `--json` | Emit the structured update-state payload. | ### [cua-driver doctor](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-doctor) Run platform-aware diagnostic probes. Exit code is non-zero when any probe is an error. **Flags:** | Name | Description | | --- | --- | | `--json` | Emit the probe report as JSON. | ### [cua-driver diagnose](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-diagnose) Print a pasteable install-layout and permission-attribution report. [Other commands](https://cua.ai/docs/cua-driver/reference/cli-reference#other-commands) ---------------------------------------------------------------------------------------- ### [cua-driver autostart](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart) Manage platform-native daemon autostart. Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance. #### [cua-driver autostart enable](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-enable) Register the autostart entry. #### [cua-driver autostart disable](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-disable) Remove the autostart entry. #### [cua-driver autostart status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-status) Print whether autostart is registered and running. #### [cua-driver autostart kick](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-kick) Start the autostart entry now without re-logging. ### [cua-driver skills](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills) Install, update, inspect, or remove the optional agent skill pack. The install script never touches agent skill directories automatically. #### [cua-driver skills install](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-install) Fetch the versioned skill pack and link detected agents. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--agent` | String | — | Restrict linking to one agent. | | `--from` | String | — | Fetch from a source such as main instead of the tagged release. | **Flags:** | Name | Description | | --- | --- | | `--all-platforms` | Keep platform-specific skill files for every platform. | #### [cua-driver skills update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-update) Refresh the local skill pack and links. #### [cua-driver skills uninstall](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-uninstall) Remove agent skill links. **Flags:** | Name | Description | | --- | --- | | `--all` | Also delete the local skill-pack copy. | #### [cua-driver skills status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-status) Report local skill-pack and per-agent link state. #### [cua-driver skills path](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-path) Print the local skill-pack path. ### [cua-driver dump-docs](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-dump-docs) Output machine-readable CLI and MCP documentation JSON. Used by the docs generator to keep reference pages in sync with the live binary. **Options:** | Name | Type | Default | Description | | --- | --- | --- | --- | | `--type` | String | all | Which docs to emit: all, cli, or mcp. | **Flags:** | Name | Description | | --- | --- | | `-p`, `--pretty` | Pretty-print JSON. | [Global options](https://cua.ai/docs/cua-driver/reference/cli-reference#global-options) ---------------------------------------------------------------------------------------- Available on all commands: * `--help` — Show help information. * `--version` — Show version number. Was this page helpful? YesNo [FAQ\ \ Frequently asked questions about Cua Driver](https://cua.ai/docs/cua-driver/guide/getting-started/faq) [MCP Tools\ \ Reference for every MCP tool Cua Driver exposes](https://cua.ai/docs/cua-driver/reference/mcp-tools) * * * ### On this page [Tool dispatch](https://cua.ai/docs/cua-driver/reference/cli-reference#tool-dispatch) [cua-driver list-tools](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-list-tools) [cua-driver describe](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-describe) [cua-driver call](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-call) [Daemon management](https://cua.ai/docs/cua-driver/reference/cli-reference#daemon-management) [cua-driver mcp](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-mcp) [cua-driver serve](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-serve) [cua-driver stop](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-stop) [cua-driver status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-status) [cua-driver mcp-config](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-mcp-config) [Trajectory recording](https://cua.ai/docs/cua-driver/reference/cli-reference#trajectory-recording) [cua-driver recording](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording) [cua-driver recording start](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-start) [cua-driver recording stop](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-stop) [cua-driver recording status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-status) [cua-driver recording render](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-recording-render) [Configuration](https://cua.ai/docs/cua-driver/reference/cli-reference#configuration) [cua-driver config](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config) [cua-driver config show](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-show) [cua-driver config get](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-get) [cua-driver config set](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-set) [cua-driver config reset](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-config-reset) [Diagnostics](https://cua.ai/docs/cua-driver/reference/cli-reference#diagnostics) [cua-driver check-update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-check-update) [cua-driver update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-update) [cua-driver doctor](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-doctor) [cua-driver diagnose](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-diagnose) [Other commands](https://cua.ai/docs/cua-driver/reference/cli-reference#other-commands) [cua-driver autostart](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart) [cua-driver autostart enable](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-enable) [cua-driver autostart disable](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-disable) [cua-driver autostart status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-status) [cua-driver autostart kick](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-autostart-kick) [cua-driver skills](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills) [cua-driver skills install](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-install) [cua-driver skills update](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-update) [cua-driver skills uninstall](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-uninstall) [cua-driver skills status](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-status) [cua-driver skills path](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-skills-path) [cua-driver dump-docs](https://cua.ai/docs/cua-driver/reference/cli-reference#cua-driver-dump-docs) [Global options](https://cua.ai/docs/cua-driver/reference/cli-reference#global-options) Copy as markdownEdit on GitHubOpen in ChatGPTOpen in Claude --- # MCP Tools | Cua Cua DriverReference MCP Tools ========= Reference for every MCP tool Cua Driver exposes `cua-driver` exposes 33 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver ''`. Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](https://cua.ai/docs/cua-driver/reference/cli-reference) for CLI-specific options like `--socket` and `--screenshot-out-file`. Tool names here match the CLI form exactly. `cua-driver list_apps` and the MCP `list_apps` tool run the same code path. **TCC auto-delegation.** When an MCP client spawns `cua-driver mcp` from an IDE terminal (Claude Code, Cursor, VS Code, Warp), macOS attributes the subprocess to the parent terminal — not `CuaDriver.app` — so AX probes fail against the wrong bundle id. `mcp` detects this and auto-launches a `cua-driver serve` daemon via `open -n -g -a CuaDriver --args serve`, then proxies every tool call through the daemon's Unix socket. Tool semantics are identical to the in-process path; no Python bridge is needed. Pass `--no-daemon-relaunch` (or set `CUA_DRIVER_MCP_NO_RELAUNCH=1`) to force in-process execution. See the [process model guide](https://cua.ai/docs/cua-driver/guide/getting-started/process-model) for the full lifecycle, failure modes, and wrapper-author guidance. [Inspection tools](https://cua.ai/docs/cua-driver/reference/mcp-tools#inspection-tools) ---------------------------------------------------------------------------------------- ### [list\_apps](https://cua.ai/docs/cua-driver/reference/mcp-tools#list_apps) List macOS apps — both currently running and installed-but-not-running — with per-app state flags: * running: is a process for this app live? (pid is 0 when false) * active: is it the system-frontmost app? (implies running) * launch\_path: filesystem path to the `.app` bundle, when known. Pass this to `launch_app` to start the app cold. * kind: `"desktop"` for `.app` bundles on macOS. * last\_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable; otherwise null. Only apps with NSApplicationActivationPolicyRegular are included — background helpers and system UI agents are filtered out. Installed apps come from scanning /Applications, /Applications/Utilities, ~/Applications, /System/Applications, and /System/Applications/Utilities. Use this for "is X installed?" as well as "is X running?". For per-window state — on-screen, on-current-Space, minimized, window titles — call list\_windows instead. For just opening an app — running or not — call launch\_app({bundle\_id: ...}) directly; list\_apps is not a prerequisite. **Arguments:** none. ### [list\_windows](https://cua.ai/docs/cua-driver/reference/mcp-tools#list_windows) List all layer-0 top-level windows currently known to WindowServer. Includes off-screen windows (minimized, on another Space, hidden-launched). Use this to find a window\_id before calling get\_window\_state. Per-record fields: window\_id, pid, app\_name, title, bounds (x/y/width/height, top-left origin), z\_index (higher = frontmost), is\_on\_screen, on\_current\_space. **Arguments:** * `on_screen_only` (boolean, optional): When true, drop windows not on the current Space. Default false. * `pid` (integer, optional): Optional pid filter. When set, only this pid's windows are returned. ### [get\_window\_state](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_window_state) Walk a running app's AX tree and return a Markdown rendering of its UI, tagging every actionable element with \[element\_index N\]. Pass those indices to click, type\_text, press\_key, etc. INVARIANT: call get\_window\_state once per turn per (pid, window\_id) before any element-indexed action. The index map is replaced by the next snapshot. Also captures a PNG screenshot of the specified window. Optional `query` filters the tree\_markdown to matching lines plus their ancestor chain (case-insensitive substring). The element\_index values are unchanged — filtering only trims the rendered Markdown. **Arguments:** * `capture_mode` (string, optional): som=AX+screenshot (default), vision=screenshot only (no AX walk), ax=AX only (no screenshot). * `pid` (integer, required): Target process ID. * `query` (string, optional): Case-insensitive filter for tree\_markdown. * `screenshot_out_file` (string, optional): When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output will contain screenshot\_file\_path instead. * `window_id` (integer, required): Target window ID from list\_windows. {"pid":844,"window_id":10725} ### [get\_accessibility\_tree](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_accessibility_tree) Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. For the full AX subtree of a single window (with interactive element indices you can click by), use `get_window_state` instead — that's the heavy per-window tool. This one is a fast discovery read that needs no TCC grants. **Arguments:** none. ### [get\_screen\_size](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_screen_size) Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale\_factor 2.0. Requires no TCC permissions. **Arguments:** none. ### [get\_cursor\_position](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_cursor_position) Return the current mouse cursor position in screen points (origin top-left). **Arguments:** none. ### [get\_config](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_config) Return the current cua-driver-rs configuration. **Arguments:** none. ### [get\_recording\_state](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_recording_state) Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. Counter increments on every recorded action tool call and resets to 1 each time recording is (re-)enabled. Pure read-only. **Arguments:** none. ### [get\_agent\_cursor\_state](https://cua.ai/docs/cua-driver/reference/mcp-tools#get_agent_cursor_state) Return the current state of **this session's** agent cursor: position, config (color, icon, label, size, opacity), enabled flag. The result is scoped to the cursor the call resolves to (precedence **explicit `cursor_id` > session identity > `"default"`**), so concurrent sessions no longer see each other's cursors and the top-level `enabled` flag is deterministic. Pass `cursor_id` to inspect a specific instance. **Arguments:** * `cursor_id` (string, optional): Cursor instance to inspect. Omit it and the call targets the calling session's own cursor (macOS); the anonymous / one-shot path targets `"default"`. [Action tools](https://cua.ai/docs/cua-driver/reference/mcp-tools#action-tools) -------------------------------------------------------------------------------- ### [launch\_app](https://cua.ai/docs/cua-driver/reference/mcp-tools#launch_app) Launch a macOS app in the background — the target does NOT come to the foreground. Provide either `bundle_id` (preferred — unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. "Calculator"). If both are given, bundle\_id wins. Optional `urls` are handed to the app as open targets — for Finder, pass a folder path to open a backgrounded Finder window there. Optional `electron_debugging_port`: opens a Chrome DevTools Protocol (CDP) server on the specified port (appends --remote-debugging-port=N to the app's argv). Use this to automate Electron/VS Code/Cursor via CDP. Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT\_INSPECTOR\_SERVER=127.0.0.1:N + TAURI\_WEBVIEW\_AUTOMATION=1). Use this for Tauri/WebKit-based apps. Optional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this in **concurrent multi-agent/multi-session** work — it returns a fresh pid + window so each session drives its own isolated window. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions clobber each other. Optional `additional_arguments`: extra argv strings appended after --args. Returns the launched app's pid, bundle\_id, name, and a `windows` array (same shape as `list_windows`) so callers can skip an extra round-trip before `get_window_state(pid, window_id)`. When the focus-steal belt-and-braces demotion check ran (target pid ≠ prior frontmost), the response also includes `self_activation_suppressed: bool` — true if focus stayed with the prior frontmost, false if the launched app held focus despite the re-demote attempt. **Arguments:** * `additional_arguments` (array of string, optional): Extra arguments appended after --args when launching. * `bundle_id` (string, optional): App bundle identifier, e.g. com.apple.calculator. Preferred over name. * `creates_new_application_instance` (boolean, optional): When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one (which makes the sessions clobber each other on single-instance apps). * `electron_debugging_port` (integer, optional): Open a Chrome DevTools Protocol server on this port (appends --remote-debugging-port=N). * `name` (string, optional): App display name. Used only when bundle\_id is absent. * `urls` (array of string, optional): Optional file paths or URLs to open with the app (e.g. a folder path for Finder). * `webkit_inspector_port` (integer, optional): Open a WebKit inspector server on this port (sets WEBKIT\_INSPECTOR\_SERVER env var). ### [kill\_app](https://cua.ai/docs/cua-driver/reference/mcp-tools#kill_app) Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). Use as escalation when the cooperative close path (hotkey cmd+q on macOS, click-the-X on Windows) failed to make the process exit. Unsaved state is lost — prefer the cooperative path first. **Arguments:** * `pid` (integer, required): PID of the process to terminate. {"pid":844} ### [bring\_to\_front](https://cua.ai/docs/cua-driver/reference/mcp-tools#bring_to_front) Activate a window so subsequent input tools with `dispatch:"foreground"` land on it without a per-call SetForegroundWindow flash. **Windows-only:** on macOS this tool returns an error pointing to the platform-native `NSRunningApplication.activate` (which the macOS input tools don't need because CGEvent.postToPid reaches backgrounded windows). On Linux this tool also stubs out; use `wmctrl -a` or `xdotool windowactivate` if you need explicit activation. **Arguments:** * `pid` (integer, required) * `window_id` (integer, optional) {"pid":844} ### [click](https://cua.ai/docs/cua-driver/reference/mcp-tools#click) Left-click against a target pid. **Prefer `element_index` over pixel coordinates** — element\_index works on backgrounded / minimized / hidden / off-Space windows, surfaces a stable handle that survives rebuilds, and tells you what you're clicking via the cached element's role + label. Reach for `x, y` only when the target is a canvas / video / WebGL / custom-drawn surface that doesn't appear in the AX tree. Two addressing modes: * element\_index + window\_id (from last get\_window\_state): AX action path. Works on backgrounded/hidden windows. No cursor move, no focus steal. element\_index cache is scoped per (pid, window\_id) and is replaced by the next snapshot of the same window — re-snapshot every turn before clicking. * x, y (window-local screenshot pixels, top-left origin of the PNG returned by get\_window\_state): CGEvent path. Synthesizes mouse events and posts to pid. Use modifier for cmd/shift/option/ctrl. Needs a visible on-screen window to anchor the conversion. action: press (default), show\_menu, pick, confirm, cancel, open. from\_zoom: set true after a zoom call to auto-translate zoom-image pixel coordinates to full-window space. **Arguments:** * `action` (string, optional): AX action: press, show\_menu, pick, confirm, cancel, open. * `count` (integer, optional): Click count (pixel path only). Default 1. * `debug_image_out` (string, optional): Optional file path. When set on a pixel-addressed click, captures a fresh screenshot, draws a red crosshair at (x, y), and writes the PNG. Use to verify coordinate spaces. Requires window\_id; incompatible with from\_zoom. * `element_index` (integer, optional): Element index from last get\_window\_state. * `from_zoom` (boolean, optional): When true, x and y are in the last zoom image for this pid; driver translates back to full-window coordinates. * `modifier` (array of string, optional): Modifier keys: cmd, shift, option/alt, ctrl. * `pid` (integer, required): Target process ID. * `window_id` (integer, optional): Target window ID. Required for element\_index. * `x` (number, optional): Window-local screenshot X coordinate. * `y` (number, optional): Window-local screenshot Y coordinate. {"pid":844} ### [double\_click](https://cua.ai/docs/cua-driver/reference/mcp-tools#double_click) Double-click at (x, y) or on an AX element identified by element\_index + window\_id. AX path (element\_index provided): performs `AXOpen` when the element advertises it (Finder items, openable list rows/cells); otherwise resolves the element's on-screen center and falls back to a pixel double-click there. Pixel path (x, y provided): two down/up pairs ~80 ms apart at the given coordinates. **Arguments:** * `element_index` (integer, optional): Element index from last get\_window\_state. Uses AX path. * `pid` (integer, required) * `window_id` (integer, optional): CGWindowID. Required when element\_index is used. * `x` (number, optional): Screen X coordinate (pixel path). * `y` (number, optional): Screen Y coordinate (pixel path). {"pid":844} ### [right\_click](https://cua.ai/docs/cua-driver/reference/mcp-tools#right_click) Right-click against a target pid. Two addressing modes: * `element_index` + `window_id` (from the last `get_window_state` snapshot) — performs `AXShowMenu` on the cached element. Pure AX RPC, works on backgrounded / hidden windows, no cursor move or focus steal. Requires a prior `get_window_state(pid, window_id)` in this turn. * `x`, `y` — synthesizes `rightMouseDown` / `rightMouseUp` CGEvent pair posted to the pid. Driver converts image-pixel → screen-point internally. `modifier` forces the CGEvent path (AX actions don't propagate modifier keys). Exactly one of `element_index` or (`x` AND `y`) must be provided. `pid` always required. `window_id` required when `element_index` is used. **Arguments:** * `element_index` (integer, optional): Element index from last get\_window\_state. Routes through AXShowMenu. Requires window\_id. * `modifier` (array of string, optional): Modifier keys held during the right-click: cmd/shift/option/ctrl. Pixel path only. * `pid` (integer, required): Target process ID. * `window_id` (integer, optional): CGWindowID. Required when element\_index is used. * `x` (number, optional): X in window-local screenshot pixels. Must be provided together with y. * `y` (number, optional): Y in window-local screenshot pixels. Must be provided together with x. {"pid":844} ### [drag](https://cua.ai/docs/cua-driver/reference/mcp-tools#drag) Press-drag-release gesture from (from\_x, from\_y) to (to\_x, to\_y) in window-local screenshot pixels — the same space get\_window\_state returns. Top-left origin of the target's window. Use for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbing a slider, repositioning a panel. `duration_ms` (default 500) is the wall-clock budget for the path between mouse-down and mouse-up; `steps` (default 20) is the number of intermediate mouseDragged events linearly interpolated along the path. Increase both for slower, more human drags; decrease for snap gestures. `modifier` keys (cmd/shift/option/ctrl) are held across the entire gesture. When `from_zoom` is true, coordinates are in the last zoom image for this pid; the driver maps them back to window coordinates before dispatching. **Arguments:** * `button` (string, optional): Mouse button used for the drag. Default: left. * `duration_ms` (integer, optional): Wall-clock duration of the drag path between mouseDown and mouseUp. Default: 500. * `from_x` (number, required): Drag-start X in window-local screenshot pixels. Top-left origin. * `from_y` (number, required): Drag-start Y in window-local screenshot pixels. Top-left origin. * `from_zoom` (boolean, optional): When true, coordinates are in the last zoom image for this pid; driver maps back to window coordinates. * `modifier` (array of string, optional): Modifier keys held across the entire gesture: cmd/shift/option/ctrl. * `pid` (integer, required): Target process ID. * `steps` (integer, optional): Number of intermediate mouseDragged events linearly interpolated along the path. Default: 20. * `to_x` (number, required): Drag-end X in window-local screenshot pixels. * `to_y` (number, required): Drag-end Y in window-local screenshot pixels. * `window_id` (integer, optional): CGWindowID for the window the pixel coordinates were measured against. Optional — when omitted the driver picks the frontmost window of pid. {"from_x":100,"from_y":200,"pid":844,"to_x":100,"to_y":200} ### [type\_text](https://cua.ai/docs/cua-driver/reference/mcp-tools#type_text) Insert text into the target pid via `AXSetAttribute(kAXSelectedText)`. Works for standard Cocoa text fields and text views. No keystrokes are synthesized — special keys (Return / Escape / arrows) go through `press_key` / `hotkey`. For Chromium / Electron inputs that don't implement `kAXSelectedText`, the tool falls back to CGEvent character synthesis automatically. Optional `element_index` + `window_id` (from the last `get_window_state` snapshot) directs the write to a specific field. Without `element_index`, the write goes to the pid's currently focused element. **Arguments:** * `delay_ms` (integer, optional): Milliseconds between characters in the CGEvent fallback path. Default 30. Ignored when the AX path succeeds. * `element_index` (integer, optional): Element index from last get\_window\_state. Directs the write to a specific field. Requires window\_id. * `pid` (integer, required): Target process ID. * `text` (string, required): Text to insert at the target's cursor. * `window_id` (integer, optional): CGWindowID. Required when element\_index is used. {"pid":844,"text":"hello"} ### [press\_key](https://cua.ai/docs/cua-driver/reference/mcp-tools#press_key) Press and release a single key, delivered to the target pid via CGEventPostToPid. No focus steal. Two delivery paths: • window\_id + element\_index: focuses the AX element first, then posts via the auth-message path (Chromium-safe). • window\_id only (no element\_index): NSMenu path — briefly activates the window WindowServer-frontmost via SLPSSetFrontProcessWithOptions (kCPSNoWindows, < 1 ms), posts WITHOUT the auth envelope so IOHIDPostEvent fires and NSApplication.sendEvent: dispatches NSMenu key equivalents. Restores prior frontmost immediately. • No window\_id: standard auth-message path. Key names: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, plus any letter or digit. Modifiers array: cmd, shift, option/alt, ctrl, fn. **Arguments:** * `element_index` (integer, optional) * `key` (string, required): Key name: return, tab, escape, up, down, etc. * `modifiers` (array of string, optional): Modifier keys: cmd, shift, option/alt, ctrl, fn. * `pid` (integer, required) * `window_id` (integer, optional) {"key":"return","pid":844} ### [hotkey](https://cua.ai/docs/cua-driver/reference/mcp-tools#hotkey) Press a combination of keys simultaneously — e.g. `["cmd", "c"]` for Copy, `["cmd", "shift", "4"]` for screenshot selection. The combo is posted directly to the target pid's event queue; the target does NOT need to be frontmost. Two delivery paths: • Default (no window\_id): auth-message envelope — Chromium/Electron apps accept the keystrokes as trusted live input on macOS 14+. • With window\_id: NSMenu path — briefly activates the target WindowServer-frontmost via SLPSSetFrontProcessWithOptions (kCPSNoWindows, < 1 ms), posts WITHOUT the auth envelope so IOHIDPostEvent fires and NSApplication.sendEvent: dispatches NSMenu key equivalents (e.g. Cmd+Z undo, Cmd+W close). Restores prior frontmost immediately. Use this path when you need native menu-bar actions on non-Chromium apps. Recognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as `press_key` (return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, letters, digits). Order: modifiers first, one non-modifier last. **Arguments:** * `keys` (array of string, required): Modifier(s) and one non-modifier key, e.g. \["cmd", "c"\]. * `pid` (integer, required): Target process ID. * `window_id` (integer, optional): When set, uses NSMenu path: briefly activates the window for menu key dispatch, then restores prior frontmost. {"keys":["cmd","c"],"pid":844} ### [set\_value](https://cua.ai/docs/cua-driver/reference/mcp-tools#set_value) Set a value on a UI element. Two modes depending on element role: * **AXPopUpButton / select dropdown**: finds the child option whose title or value matches `value` (case-insensitive) and AXPresses it directly — the native macOS popup menu is never opened, so focus is never stolen. Use this for HTML