Cua Driver

Connect background desktop control to your agent.

Pick your operating system, install the open-source driver, then connect Claude Code, Codex, Hermes, or any MCP client to the same stdio server.

Install for macOS Pick a client lane

Your setup

Selected macOS · Stable

CuaDriver.app + CLI

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

Grant Accessibility before connecting an agent.

Grant Screen Recording for screenshots and visual grounding.

Let the MCP server launch the app daemon when possible.

Install

Start with your machine.

We preselect the OS your browser reports. Switch lanes whenever you are installing on a different host.

macOS installer

CuaDriver.app + CLI

Installs CuaDriver.app in /Applications and symlinks ~/.local/bin/cua-driver for your shell.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

Start daemon

open -n -g -a CuaDriver --args serve
cua-driver status

Verify

cua-driver call check_permissions
cua-driver status

Native background control

Click, type, scroll, inspect accessibility trees, and capture window state without stealing cursor or focus.

One MCP + CLI surface

The stdio MCP server and shell commands call the same driver handlers, so humans and agents share the harness.

Daemon-aware sessions

On macOS, cua-driver mcp can auto-launch the app daemon and proxy calls through the right TCC context.

Client lanes

Choose the agent surface you already use.

After installing on macOS, every lane points at cua-driver mcp. The wrapper changes; the desktop control surface stays the same.

Full docs

coding agents

Claude Code

Register the standard MCP server. Add the compatibility server when you want Claude Code computer-use-style screenshot grounding.

Standard MCP

claude mcp add --transport stdio cua-driver -- cua-driver mcp

Screenshot-grounded mode

claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat

openai

Codex

Add the local stdio server once. Codex then sees the same tool surface the CLI exposes.

Add MCP server

codex mcp add cua-driver -- cua-driver mcp

nous

Hermes

Generate the Hermes config and paste it into the local Hermes YAML file.

Generate config

cua-driver mcp-config --client hermes
# paste into ~/.hermes/config.yaml

cursor / opencode / custom

Other MCP clients

Emit a client-specific snippet, or use the generic MCP server shape for your own broker.

Client snippets

cua-driver mcp-config --client cursor
cua-driver mcp-config --client opencode

Generic server

cua-driver mcp-config

First run

The loop is launch, inspect, act, verify.

Element indexes are refreshed on every snapshot, so the pre-action and post-action window state are part of the contract.

Step 1

Start the daemon

Persistent sessions keep element indexes and per-run state alive across tool calls.

open -n -g -a CuaDriver --args serve
cua-driver status

Step 2

Launch and inspect

Launch returns a pid and windows. The snapshot gives your agent element indexes plus a screenshot.

cua-driver call launch_app '{"bundle_id":"com.apple.calculator"}'
cua-driver call get_window_state '{"pid":844,"window_id":10725}'

Step 3

Act, then verify

Click or type by element_index, then snapshot again before claiming the action worked.

cua-driver call click '{"pid":844,"window_id":10725,"element_index":14}'
cua-driver call get_window_state '{"pid":844,"window_id":10725}'

Production wrapper note

If you are wrapping Cua Driver in Hermes or another broker, let cua-driver mcp own daemon startup, treat stdio MCP as the contract, and reconnect the MCP transport if the daemon becomes unreachable.

View on GitHub

Verify permissions with cua-driver call check_permissions.

Use get_window_state before and after every action.

Stop the daemon with cua-driver stop when debugging.