packages/cua-driver/README.md
Cross-platform background computer-use driver for AI agents. Speaks MCP over stdio; drives native apps without stealing focus.
Based on trycua/cua with Qwen-specific extensions: relative-coordinate normalization (0–1000 space for Qwen-VL models), vendored patches, and qwen-code integration.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/install.sh)"
irm https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/install.ps1 | iex
# macOS / Linux
CUA_DRIVER_RS_VERSION=0.7.0 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/install.sh)"
# Windows
$env:CUA_DRIVER_RS_VERSION = "0.7.0"
irm https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/install.ps1 | iex
Note: After installation, restart your terminal or IDE for PATH changes to take effect.
qwen-cua-driver --version
# Expected: cua-driver 0.7.0
macOS requires Accessibility and Screen Recording permissions:
# Grant permissions (launches the driver so the dialog attributes correctly)
qwen-cua-driver permissions grant
# Check status
qwen-cua-driver permissions status
# List running apps
qwen-cua-driver call list_apps '{}'
# List available tools
qwen-cua-driver list-tools
qwen mcp add --transport stdio cua-driver -- qwen-cua-driver mcp
With relative-coordinate normalization (recommended for Qwen-VL models):
qwen mcp add-json --scope user cua-computer-use '{"command":"qwen-cua-driver","args":["mcp"],"env":{"CUA_DRIVER_RS_COORDINATE_SPACE":"1"}}'
Or add to .qwen/settings.json:
{
"mcpServers": {
"cua-computer-use": {
"command": "qwen-cua-driver",
"args": ["mcp"],
"env": {
"CUA_DRIVER_RS_COORDINATE_SPACE": "1"
}
}
}
}
Note: If you enable the MCP server manually, disable the built-in computer-use to avoid conflicts:
json{ "tools": { "computerUse": { "enabled": false } } }
Standard registration:
claude mcp add --transport stdio cua-driver -- qwen-cua-driver mcp
Computer-use compatibility mode (grounds Claude Code's vision flow on cua-driver screenshots):
claude mcp add --transport stdio cua-computer-use -- qwen-cua-driver mcp --claude-code-computer-use-compat
Or via JSON (recommended for Windows where arg parsing can lose flags):
claude mcp add-json --scope user cua-computer-use '{"command":"qwen-cua-driver","args":["mcp","--claude-code-computer-use-compat"]}'
codex mcp add cua-driver -- qwen-cua-driver mcp
Generate a client-specific config snippet:
qwen-cua-driver mcp-config --client cursor
qwen-cua-driver mcp-config --client opencode
qwen-cua-driver mcp-config --client hermes
Or get the generic mcpServers JSON shape:
qwen-cua-driver mcp-config
For models that output normalized 0–1000 coordinates (e.g. Qwen-VL computer_use), enable coordinate normalization:
# Via environment variable (set before starting the MCP server)
export CUA_DRIVER_RS_COORDINATE_SPACE=1
# Optional: change full-scale (default 1000, some models use 999)
export CUA_DRIVER_RS_COORDINATE_SCALE=999
When enabled:
get_window_state / get_desktop_state report screenshot_width/height as 1000click / drag / scroll x/y accept 0–1000 values (auto-converted to pixels)move_cursor uses 0–1000 in screen space/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/uninstall.sh)"
irm https://raw.githubusercontent.com/QwenLM/qwen-code/main/packages/cua-driver/scripts/uninstall.ps1 | iex
| Platform | Status | Notes |
|---|---|---|
| macOS (Apple Silicon) | Stable | Full AX tree + screenshot + input |
| macOS (Intel) | Stable | Same as above |
| Windows x86_64 | Stable | UIA + screenshot + input |
| Windows ARM64 | Stable | Same as x86_64 |
| Linux x86_64 | Pre-release | X11 + AT-SPI; Wayland partial |
| Linux ARM64 | Pre-release | Same limitations as x86_64 |