Connect your agent

An agent reaches Cua Driver in one of two ways: an MCP client launches cua-driver mcp, or a skill teaches a shell-capable agent to run cua-driver call <tool>. The harness owns the model and the loop; Cua Driver never calls a model API.

If you installed Cua Driver with Cua Spaces, its Set up button connects Claude Code and Codex for you.

Connect with one command#

cua-driver connect finds Claude Code, Codex, Cursor and Factory Droid on the computer, connects each one to Cua Driver (the server name is cua-driver) and installs the agent skill for the ones that have a skills folder. The installer runs it for you. It is safe to run again: an agent that is already connected, including one connected under the older Claude Code name cua-computer-use, is left alone. An agent whose cua-driver server launches a different Cua Driver, such as the one Cua Spaces sets up, is reported as using another Cua Driver and left as is. cua-driver connect --replace switches Claude Code, Codex and Cursor to this driver through the same step as Set up in Cua Spaces, backing up the config file first. For Factory Droid, or a Claude Code server still named cua-computer-use, remove that server and run cua-driver connect again. Use --client claude, --client codex, --client cursor or --client droid to pick one, --dry-run to preview, and --json for machine-readable output. Restart the agent afterwards. Cursor's ~/.cursor/mcp.json and Droid's ~/.factory/mcp.json and settings.json are merged, never replaced.

For any other agent, or to see the exact setup, use mcp-config below.

Register the MCP server#

To add the skill and MCP server to every agent on the machine in one step, use the cua installer: curl -fsSL https://cua.ai/install.sh | sh -s -- --select cua-driver. Add --no-skills to leave the skill out.

mcp-config prints the exact command or JSON for your client, with your installed binary's absolute path. Run what it prints, then restart the client. It also installs the agent skill for that client and prints one line saying where; add --no-skills to skip that:

cua-driver mcp-config --client <client>

Harness	Setup	Notes
Claude Code	`cua-driver connect`, or `--client claude`, which prints `claude mcp add-json --scope user cua-driver '{…}'`	Install the skill for native skill activation.
Codex (CLI, IDE, app)	`--client codex`, which prints `codex mcp add cua-driver -- <path> mcp`	Codex's own approval policy also applies.
Cursor	`--client cursor`; paste into `~/.cursor/mcp.json` or `.cursor/mcp.json`
Antigravity CLI (Gemini)	`--client antigravity`; merge into `~/.gemini/config/mcp_config.json`	`--client gemini` is a legacy alias. Building on the Gemini API directly? See Gemini.
OpenClaw	`--client openclaw`, which prints `openclaw mcp set cua-driver '{…}'`	On macOS, a gateway-spawned server does not inherit OpenClaw.app's grants.
Hermes	Built in: `hermes tools enable computer_use --platform cli`, then `hermes -t computer_use chat`	Repair with `hermes computer-use install` and `doctor`. Do not add a second raw MCP server.
Prime Agent	`cua-driver skills install`, then `/reload` and `/skill:cua-driver`	Calls the CLI; no MCP.
Factory Droid	`cua-driver connect --client droid`, then `droid exec --auto medium "…"`	MCP is the supported setup. Droid asks for `--auto high` before any MCP tool not marked read-only, so `connect` also rates each action tool `medium` under `mcpAutonomyOverrides` in `~/.factory/settings.json` and keeps `kill_app` at Droid's default. Ratings you set are kept. `--client droid` on `mcp-config` prints only the `droid mcp add` line.
OpenCode, ZCode	`--client opencode`, `--client zcode`
Qwen Code	`--client qwen`, which prints `qwen mcp add cua-driver <path> mcp`
Pi	`--client pi`	No MCP: runs one-shot `cua-driver call …` commands.
Kimi Code	`kimi mcp add cua-driver -- <path> mcp`, then `kimi mcp test cua-driver`	No preset.
GitHub Copilot CLI	Add `{"mcpServers": {"cua-driver": {"type": "local", "command": "<path>", "args": ["mcp"], "tools": ["*"]}}}` to `~/.copilot/mcp-config.json`	No preset.
Muse Code (macOS, Linux)	Merge `{"mcp_servers": {"cua-driver": {"enabled": true, "transport": "stdio", "command": "<path>", "args": ["mcp"]}}}` into `$XDG_CONFIG_HOME/muse/settings.json`, or `~/.config/muse/settings.json`	No preset. Start a new Muse session; MCP servers load at startup.
T3 Code	Register Cua Driver in the harness that T3 Code launches

Find <path> with command -v cua-driver. The full roster is in the mcp-config reference. Any other client that accepts the standard shape can use this (cua-driver mcp-config with no flag):

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}

Model providers map to harnesses: Claude through Claude Code, OpenAI through Codex, Gemini through Antigravity, Kimi through Kimi Code, Qwen through Qwen Code. To call Gemini 4 Argon from your own agent loop instead, see Gemini. MiniMax documents setups for Codex and Claude Code.

Registering a client does not choose a permission mode. On macOS, cua-driver mcp proxies to the CuaDriver.app daemon, whose launch flags decide. On Windows and Linux it owns its runtime: set CUA_DRIVER_PERMISSION_MODE in the client's env block, or use cua-driver mcp --socket <endpoint> to reach a configured daemon. The default, standard, allows input to every app.

Install the agent skill#

The skill teaches an agent to pick tools, address elements, keep focus, and verify each action. mcp-config --client <client> and the cua installer install it for the agents they set up. To install it for every agent on the machine, or for one you set up another way, run skills install. It links into Claude Code, Codex, Cursor, Prime Agent, OpenClaw, OpenCode, Antigravity, Hermes, and Pi:

cua-driver skills install
cua-driver skills status

If status reports a client's skill directory as absent, create it (~/.agents/skills for Codex, ~/.claude/skills for Claude Code, ~/.gemini/config/skills for the Antigravity IDE, ~/.gemini/antigravity-cli/skills for the Antigravity CLI) and rerun. Add --all-platforms to keep the macOS, Windows, and Linux guides together. OpenClaw can use ClawHub instead: clawhub install @cua/driver. Cua Driver 0.28.0+ also serves the skill as MCP resources; whether that activates it as a skill is up to the client. Most clients never read resources on their own, so the server also offers a read-only get_guide tool: get_guide({topic}) returns the guidance for drag, browser, permissions, batching, menus or the overview, with no skill installed.

Agent SDKs#

Examples in libs/cua-driver/examples/agent-sdks (Python and TypeScript):

SDK	Route	Run
Claude Agent SDK	Native callbacks calling `CuaDriver.create()` in process	`claude_agent.py --route native` / `npm run claude -- --route native`
Claude Agent SDK	MCP	`claude_agent.py --route mcp` / `npm run claude -- --route mcp`
Codex SDK	MCP (it has no custom tool callbacks)	`codex_agent.py` / `npm run codex`

They remove interactive approval prompts: run only trusted tasks.

Gemini#

Add Cua Driver to Antigravity, or call the Gemini API from your own agent loop: see Computer use with Gemini.

Local models#

Run Cua Driver with a model on your own machine, through Ollama or llama.cpp: see Run Cua Driver with local models.

Setup for one agent#

Claude Code, Codex, Cursor, Hermes and OpenClaw each have a short page. To give an agent Cua Spaces instead, see Connect your agent and Connect an agent over MCP.