Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cua-driver): install the skill pack when setting up an agent, and add get_guide (#5491)

Francesco Bonacci8637cae79b3d
diff --git a/.github/scripts/cua-driver-mcp-compat/expected-tools.json b/.github/scripts/cua-driver-mcp-compat/expected-tools.json
index 3b4d96cfbf..d70538b1a2 100644
--- a/.github/scripts/cua-driver-mcp-compat/expected-tools.json
+++ b/.github/scripts/cua-driver-mcp-compat/expected-tools.json
@@ -31,6 +31,7 @@
"get_config",
"get_cursor_position",
"get_desktop_state",
+ "get_guide",
"get_recording_state",
"get_screen_size",
"get_session",
diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.py
index afdae142a0..b856bee7d4 100644
--- a/.github/scripts/tests/test_cua_driver_release_wiring.py
+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py
@@ -1105,7 +1105,7 @@ fi
self.assertEqual(
len(expected["baseTools"]), len(set(expected["baseTools"]))
)
- self.assertEqual(len(expected["baseTools"]), 61)
+ self.assertEqual(len(expected["baseTools"]), 62)
self.assertEqual(
expected["outputSchemaCountByPlatform"],
{"darwin": 35, "linux": 39, "win32": 35},
diff --git a/docs/content/docs/cua-driver/guides/connect-your-agent.mdx b/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
index d41a807795..a67f26f159 100644
--- a/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
+++ b/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
@@ -15,9 +15,12 @@ never calls a model API.
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:
+installed binary's absolute path. Run what it prints, then restart the client.
+It also installs the [agent skill](#install-the-agent-skill) for that client and
+prints one line saying where; add `--no-skills` to skip that:
```bash test="cli-shape" id="cua-driver-mcp-config"
cua-driver mcp-config --client <client>
@@ -72,8 +75,10 @@ loop instead, see [Computer use with Gemini](/cua-driver/guides/gemini). MiniMax
## Install the agent skill
The skill teaches an agent to pick tools, address elements, keep focus, and
-verify each action. It links into Claude Code, Codex, Prime Agent, OpenClaw,
-OpenCode, Antigravity, Hermes, and Pi:
+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:
```bash test="cli-shape" id="cua-driver-skills-install"
cua-driver skills install
@@ -87,7 +92,10 @@ If `status` reports a client's skill directory as absent, create it
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.
+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
diff --git a/docs/content/docs/cua-driver/reference/cli/index.mdx b/docs/content/docs/cua-driver/reference/cli/index.mdx
index f517f3a5a8..843e25750f 100644
--- a/docs/content/docs/cua-driver/reference/cli/index.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/index.mdx
@@ -25,7 +25,7 @@ Serve MCP, print client config, and list, describe or call tools from the shell.
| Command | Description |
| --- | --- |
| <span id="cua-driver-mcp"></span>[`cua-driver mcp`](/cua-driver/reference/cli/mcp#cua-driver-mcp) | Run the stdio MCP server. |
-| <span id="cua-driver-mcp-config"></span>[`cua-driver mcp-config`](/cua-driver/reference/cli/mcp#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported). |
+| <span id="cua-driver-mcp-config"></span>[`cua-driver mcp-config`](/cua-driver/reference/cli/mcp#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
| <span id="cua-driver-list-tools"></span>[`cua-driver list-tools`](/cua-driver/reference/cli/mcp#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
| <span id="cua-driver-describe"></span>[`cua-driver describe`](/cua-driver/reference/cli/mcp#cua-driver-describe) | Print a tool's full description and JSON input schema. |
| <span id="cua-driver-call"></span>[`cua-driver call`](/cua-driver/reference/cli/mcp#cua-driver-call) | Invoke an MCP tool through the running daemon. |
diff --git a/docs/content/docs/cua-driver/reference/cli/mcp.mdx b/docs/content/docs/cua-driver/reference/cli/mcp.mdx
index f0d1784277..7b3470d07d 100644
--- a/docs/content/docs/cua-driver/reference/cli/mcp.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/mcp.mdx
@@ -13,7 +13,7 @@ description: "Serve MCP, print client config, and list, describe or call tools f
| Command | Description |
| --- | --- |
| [`cua-driver mcp`](#cua-driver-mcp) | Run the stdio MCP server. |
-| [`cua-driver mcp-config`](#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported). |
+| [`cua-driver mcp-config`](#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
| [`cua-driver list-tools`](#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
| [`cua-driver describe`](#cua-driver-describe) | Print a tool's full description and JSON input schema. |
| [`cua-driver call`](#cua-driver-call) | Invoke an MCP tool through the running daemon. |
@@ -55,9 +55,9 @@ cua-driver mcp --socket /tmp/cua-driver.sock
## `cua-driver mcp-config`
-Print client-specific connection guidance (MCP config where supported).
+Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.
-Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode.
+Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.
```text output
cua-driver mcp-config [OPTIONS]
@@ -66,6 +66,7 @@ cua-driver mcp-config [OPTIONS]
| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| <span id="cua-driver-mcp-config--client"></span>`--client` | string | | Client name to print configuration for. |
+| <span id="cua-driver-mcp-config--no-skills"></span>`--no-skills` | boolean | `false` | With --client, do not install the cua-driver skill pack for that agent. |
**Examples**
@@ -73,8 +74,11 @@ cua-driver mcp-config [OPTIONS]
# Print a generic mcpServers entry
cua-driver mcp-config
-# Print setup for Codex
+# Print setup for Codex and install its skill pack
cua-driver mcp-config --client codex
+
+# Print setup for Codex only
+cua-driver mcp-config --client codex --no-skills
```
## `cua-driver list-tools`
diff --git a/docs/content/docs/cua-driver/reference/index.mdx b/docs/content/docs/cua-driver/reference/index.mdx
index 5cc98b33a9..34ed8a9610 100644
--- a/docs/content/docs/cua-driver/reference/index.mdx
+++ b/docs/content/docs/cua-driver/reference/index.mdx
@@ -44,4 +44,4 @@ description: "Every cua-driver command and every MCP tool on macOS, Linux and Wi
| [Session tools](/cua-driver/reference/mcp-tools/sessions) | Start, escalate, inspect and end lifecycle sessions. 6 tools. |
| [Agent cursor tools](/cua-driver/reference/mcp-tools/agent-cursor) | Show, animate and style the agent cursor. 4 tools. |
| [Recording tools](/cua-driver/reference/mcp-tools/recording) | Record and replay trajectories. 5 tools. |
-| [Configuration and maintenance tools](/cua-driver/reference/mcp-tools/maintenance) | Configuration, permissions, health, updates and extensions. 6 tools. |
+| [Configuration and maintenance tools](/cua-driver/reference/mcp-tools/maintenance) | Configuration, permissions, health, updates, extensions and on-demand guides. 7 tools. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx
index a987f6f22c..9cc290ffe2 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx
@@ -351,7 +351,7 @@ Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
## `invoke_menu`
-Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels.
+Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:"menus"})`.
Effect: destructive. Platforms: macOS, Linux, Windows.
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx
index 479590c18f..b1400a5fa1 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx
@@ -40,7 +40,7 @@ TARGET BY NAME (no earlier read needed, so one batch can cross screens): a step
WAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is &#123;role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?&#125;: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.
Example (fill a form, submit, confirm the dialog, check the result):
-&#123;"steps":[&#123;"set_value":&#123;"app":"Safari","role":"textfield","name":"Email","value":"[email protected]"&#125;&#125;,&#123;"click":&#123;"role":"button","name":"Submit"&#125;,"expect":[&#123;"role":"button","name":"Confirm"&#125;]&#125;,&#123;"click":&#123;"role":"button","name":"Confirm"&#125;,"expect":[&#123;"name":"Confirm","gone":true&#125;,&#123;"text":"Thanks"&#125;]&#125;],"observe":&#123;&#125;&#125;.
+&#123;"steps":[&#123;"set_value":&#123;"app":"Safari","role":"textfield","name":"Email","value":"[email protected]"&#125;&#125;,&#123;"click":&#123;"role":"button","name":"Submit"&#125;,"expect":[&#123;"role":"button","name":"Confirm"&#125;]&#125;,&#123;"click":&#123;"role":"button","name":"Confirm"&#125;,"expect":[&#123;"name":"Confirm","gone":true&#125;,&#123;"text":"Thanks"&#125;]&#125;],"observe":&#123;&#125;&#125; Batching rules: `get_guide({topic:"batching"})`.
Effect: destructive. Platforms: macOS, Linux, Windows.
@@ -84,7 +84,7 @@ Example:
const app = await cua.getApp("Calculator");
for (const key of ["7", "multiply", "6", "equals"]) await app.click(&#123;role: "button", name: key&#125;);
const [display] = await app.query(&#123;role: "statictext"&#125;);
-return display.value;.
+return display.value; Batching rules: `get_guide({topic:"batching"})`.
Effect: destructive. Platforms: macOS, Linux, Windows.
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
index ebfb3d7a33..5665cfc345 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
@@ -215,7 +215,7 @@ Record and replay trajectories. [Reference](/cua-driver/reference/mcp-tools/reco
## Configuration and maintenance tools
-Configuration, permissions, health, updates and extensions. [Reference](/cua-driver/reference/mcp-tools/maintenance).
+Configuration, permissions, health, updates, extensions and on-demand guides. [Reference](/cua-driver/reference/mcp-tools/maintenance).
| Tool | Description | Platforms |
| --- | --- | --- |
@@ -225,3 +225,4 @@ Configuration, permissions, health, updates and extensions. [Reference](/cua-dri
| <span id="health_report"></span>[`health_report`](/cua-driver/reference/mcp-tools/maintenance#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
| <span id="check_for_update"></span>[`check_for_update`](/cua-driver/reference/mcp-tools/maintenance#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
| <span id="install_extension"></span>[`install_extension`](/cua-driver/reference/mcp-tools/maintenance#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
+| <span id="get_guide"></span>[`get_guide`](/cua-driver/reference/mcp-tools/maintenance#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx
index a068303ee8..f6fbfe2f31 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx
@@ -1,6 +1,6 @@
---
title: "Configuration and maintenance tools"
-description: "Configuration, permissions, health, updates and extensions."
+description: "Configuration, permissions, health, updates, extensions and on-demand guides."
---
{/*
@@ -20,6 +20,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
| [`health_report`](#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
| [`check_for_update`](#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
| [`install_extension`](#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
+| [`get_guide`](#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
@@ -161,7 +162,7 @@ Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants: Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass &#123;"prompt": false&#125; for a purely read-only status check.
-Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent.
+Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent. How to get them granted: `get_guide({topic:"permissions"})`.
**macOS parameters**
@@ -173,7 +174,7 @@ Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight A
</Tab>
<Tab value="Linux">
-Check required permissions for cua-driver-rs on Linux.
+Check required permissions for cua-driver-rs on Linux. How to get them granted: `get_guide({topic:"permissions"})`.
**Linux parameters**
@@ -184,7 +185,7 @@ Check required permissions for cua-driver-rs on Linux.
</Tab>
<Tab value="Windows">
-Check required permissions for cua-driver-rs on Windows.
+Check required permissions for cua-driver-rs on Windows. How to get them granted: `get_guide({topic:"permissions"})`.
**Windows parameters**
@@ -281,3 +282,14 @@ Effect: destructive. Platforms: macOS, Linux, Windows.
```json
{"name":"perception"}
```
+
+## `get_guide`
+
+Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_guide--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="get_guide--topic"></span>`topic` | `string` | | One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
index 67afb94d5a..9636d0b2b3 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
@@ -58,7 +58,7 @@ Effect: mutating. Platforms: macOS, Linux, Windows.
## `get_browser_state`
-Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.
+Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:"browser"})`.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
@@ -77,7 +77,7 @@ Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
## `browser_prepare`
-Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy &#123;"kind":"existing_profile"&#125; when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.
+Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy &#123;"kind":"existing_profile"&#125; when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:"browser"})`.
Effect: destructive. Platforms: macOS, Linux, Windows.
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx
index deed8f894a..b187935d11 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx
@@ -41,7 +41,7 @@ Use for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbin
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.
-A window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:"drag" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:"foreground", which briefly fronts the window and moves the physical pointer.
+A window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:"drag" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:"foreground", which briefly fronts the window and moves the physical pointer. Limits and fallbacks: `get_guide({topic:"drag"})`.
**macOS parameters**
@@ -64,7 +64,7 @@ A window-scoped drag (pid + window_id) runs in the background by default: the ge
</Tab>
<Tab value="Linux">
-Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release); it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal.
+Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release); it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal. Limits and fallbacks: `get_guide({topic:"drag"})`.
**Linux parameters**
@@ -89,7 +89,7 @@ Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local
</Tab>
<Tab value="Windows">
-Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background, the OS move/resize loop needs real pointer input, so they return background_unavailable; re-issue those with delivery_mode:"foreground".
+Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background, the OS move/resize loop needs real pointer input, so they return background_unavailable; re-issue those with delivery_mode:"foreground". Limits and fallbacks: `get_guide({topic:"drag"})`.
**Windows parameters**
diff --git a/docs/content/docs/start-here/drive-your-first-app.mdx b/docs/content/docs/start-here/drive-your-first-app.mdx
index fcb3c5ac4d..7918806a64 100644
--- a/docs/content/docs/start-here/drive-your-first-app.mdx
+++ b/docs/content/docs/start-here/drive-your-first-app.mdx
@@ -154,9 +154,9 @@ and retry. Resolve permission or display errors before connecting the agent.
Choose one integration for your agent. A skill teaches the agent to use the
Cua Driver CLI; MCP registration exposes Cua Driver as a tool server.
-`mcp-config` only prints setup instructions: you must run the registration
-command it prints. Use the output from your machine, not the illustrative
-paths below.
+`mcp-config` prints the registration command, which you must run, and installs
+the skill for that agent (add `--no-skills` to skip it). Use the output from your
+machine, not the illustrative paths below.
<Tabs items={['Claude Code', 'Codex', 'Prime Agent', 'OpenClaw', 'Hermes']}>
<Tab value="Claude Code">
diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
index 0fa849b862..c3d473a969 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
@@ -123,3 +123,4 @@ Load on demand; do not reabsorb these into this file:
- [BROWSER.md](BROWSER.md): exact page binding and typed browser actions; only when the requested method permits them.
- [RECORDING.md](RECORDING.md): capture lifecycle, artifact checks, replay limits.
- [EMBEDDING.md](EMBEDDING.md): trusted application-host integration, not routine GUI operation.
+- `get_guide({topic})`: an MCP tool that returns the drag, browser, permissions, batching and menus sections of these files on demand, with no skill install or resource read. `overview` returns this file.
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs
index a5ce1cc99c..8e4ed0d557 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs
@@ -874,6 +874,7 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {
| "get_agent_cursor_state"
| "get_recording_state"
| "check_for_update"
+ | "get_guide"
| "health_report"
| "probe" => RiskClass::R0,
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/guide.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/guide.rs
new file mode 100644
index 0000000000..a960ca8aeb
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/guide.rs
@@ -0,0 +1,601 @@
+//! `get_guide`: read-only, on-demand sections of the compiled-in skill pack.
+//!
+//! Most MCP clients hand the model only the server instructions and the tool
+//! descriptions. MCP resources such as `skill://cua-driver/SKILL.md` are
+//! pull-only and rarely read, while a tool is called. This one returns the
+//! guidance for a topic (drag, browser, permissions, ...) from the skill files
+//! compiled into this binary, so the text matches the running driver and works
+//! with no skill installed.
+
+use std::sync::OnceLock;
+
+use async_trait::async_trait;
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use crate::mcp_skills::embedded_file;
+use crate::protocol::ToolResult;
+use crate::tool::{Tool, ToolDef};
+use crate::tool_args::parse_typed_input;
+
+/// The host platform a guide is cut for. Platform guides (`MACOS.md`,
+/// `WINDOWS.md`, `LINUX.md`) are all compiled in; a topic reads only the
+/// current host's.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Platform {
+ Macos,
+ Windows,
+ Linux,
+}
+
+impl Platform {
+ pub const ALL: [Platform; 3] = [Platform::Macos, Platform::Windows, Platform::Linux];
+
+ pub const fn current() -> Platform {
+ if cfg!(target_os = "macos") {
+ Platform::Macos
+ } else if cfg!(target_os = "windows") {
+ Platform::Windows
+ } else {
+ Platform::Linux
+ }
+ }
+
+ pub const fn label(self) -> &'static str {
+ match self {
+ Platform::Macos => "macOS",
+ Platform::Windows => "Windows",
+ Platform::Linux => "Linux",
+ }
+ }
+}
+
+/// One heading of one skill file. `only` limits it to a platform.
+struct Part {
+ file: &'static str,
+ heading: &'static str,
+ only: Option<Platform>,
+}
+
+const fn any(file: &'static str, heading: &'static str) -> Part {
+ Part {
+ file,
+ heading,
+ only: None,
+ }
+}
+
+const fn on(platform: Platform, file: &'static str, heading: &'static str) -> Part {
+ Part {
+ file,
+ heading,
+ only: Some(platform),
+ }
+}
+
+struct Topic {
+ name: &'static str,
+ summary: &'static str,
+ parts: &'static [Part],
+}
+
+/// The topics, in the order they are listed. A part names a heading by its
+/// exact text; the section runs to the next heading of the same or a higher
+/// level. A test resolves every part on every platform, so a renamed heading
+/// fails there instead of silently emptying a topic.
+const TOPICS: &[Topic] = &[
+ Topic {
+ name: "overview",
+ summary: "the whole SKILL.md: loop, rules, failure map",
+ parts: &[any("SKILL.md", "cua-driver")],
+ },
+ Topic {
+ name: "drag",
+ summary: "drag and drop: background limits, fallbacks, browser drags",
+ parts: &[
+ on(
+ Platform::Macos,
+ "MACOS.md",
+ "`delivery_mode` on the pointer family (macOS)",
+ ),
+ on(
+ Platform::Windows,
+ "WINDOWS.md",
+ "How the contract is enforced per call: the `delivery_mode` field",
+ ),
+ on(Platform::Windows, "WINDOWS.md", "Intent → tool mapping"),
+ on(Platform::Linux, "LINUX.md", "Delivery"),
+ any("BROWSER.md", "Extended pointer actions"),
+ ],
+ },
+ Topic {
+ name: "browser",
+ summary: "page-aware browser tools: bind, snapshot, act, recover",
+ parts: &[
+ any("BROWSER.md", "Choose the page-aware route first"),
+ any("BROWSER.md", "4. Mutate with typed tools"),
+ any("BROWSER.md", "Browser chrome and native fallbacks"),
+ any("BROWSER.md", "Recovery rules"),
+ ],
+ },
+ Topic {
+ name: "permissions",
+ summary: "OS permissions and how to get them granted",
+ parts: &[
+ on(Platform::Macos, "MACOS.md", "Prerequisites: macOS"),
+ on(
+ Platform::Macos,
+ "MACOS.md",
+ "Install and approve permissions",
+ ),
+ on(
+ Platform::Windows,
+ "WINDOWS.md",
+ "Prerequisites: check before starting",
+ ),
+ on(Platform::Linux, "LINUX.md", "Capture recovery"),
+ ],
+ },
+ Topic {
+ name: "batching",
+ summary: "run_steps and run_script: several actions in one call",
+ parts: &[
+ any("WORKFLOW.md", "Batch known actions"),
+ any("WORKFLOW.md", "Script a flow"),
+ ],
+ },
+ Topic {
+ name: "menus",
+ summary: "native menu bars with invoke_menu",
+ parts: &[
+ on(
+ Platform::Macos,
+ "MACOS.md",
+ "Navigating native menu bars (AXMenuBar)",
+ ),
+ on(
+ Platform::Macos,
+ "MACOS.md",
+ "Menus opened in the background keep the user's keyboard",
+ ),
+ on(
+ Platform::Windows,
+ "WINDOWS.md",
+ "Snapshot-bound element mode (preferred)",
+ ),
+ on(Platform::Linux, "LINUX.md", "Native application menus"),
+ ],
+ },
+];
+
+/// The topic names, in listing order.
+pub fn topic_names() -> Vec<&'static str> {
+ TOPICS.iter().map(|topic| topic.name).collect()
+}
+
+/// A resolved guide: the text to return and where each piece came from.
+#[derive(Debug)]
+pub struct Guide {
+ pub topic: &'static str,
+ pub platform: Platform,
+ pub text: String,
+ /// `(file, heading)` of every section in `text`.
+ pub sources: Vec<(&'static str, &'static str)>,
+}
+
+/// Why a guide could not be returned.
+#[derive(Debug, PartialEq, Eq)]
+pub enum GuideError {
+ UnknownTopic(String),
+ /// A section named by a topic is missing from the embedded files. A test
+ /// keeps this from shipping; it is an error rather than a panic so a
+ /// broken pack never takes the server down.
+ MissingSection {
+ file: &'static str,
+ heading: &'static str,
+ },
+}
+
+/// The topic `name` cut for `platform`.
+pub fn guide_for(name: &str, platform: Platform) -> Result<Guide, GuideError> {
+ let wanted = name.trim().to_ascii_lowercase();
+ let topic = TOPICS
+ .iter()
+ .find(|topic| topic.name == wanted)
+ .ok_or_else(|| GuideError::UnknownTopic(name.trim().to_owned()))?;
+ let mut text = format!("Cua Driver guide: {} ({})\n", topic.name, platform.label());
+ let mut sources = Vec::new();
+ let mut files: Vec<&'static str> = Vec::new();
+ for part in topic
+ .parts
+ .iter()
+ .filter(|part| part.only.is_none_or(|only| only == platform))
+ {
+ let section = embedded_file(part.file)
+ .and_then(|body| section(body, part.heading))
+ .ok_or(GuideError::MissingSection {
+ file: part.file,
+ heading: part.heading,
+ })?;
+ text.push_str(&format!("\n=== {} ===\n\n{section}\n", part.file));
+ sources.push((part.file, part.heading));
+ if !files.contains(&part.file) {
+ files.push(part.file);
+ }
+ }
+ let full: Vec<String> = files
+ .iter()
+ .map(|file| format!("skill://cua-driver/{file}"))
+ .collect();
+ text.push_str(&format!(
+ "\nFull files: {}. Other topics: {}.\n",
+ full.join(", "),
+ topic_names()
+ .into_iter()
+ .filter(|other| *other != topic.name)
+ .collect::<Vec<_>>()
+ .join(", ")
+ ));
+ Ok(Guide {
+ topic: topic.name,
+ platform,
+ text,
+ sources,
+ })
+}
+
+/// What `get_guide` with no topic returns.
+fn index_text() -> String {
+ let mut text = String::from("Cua Driver guide topics. Call get_guide({topic}) with one:\n");
+ for topic in TOPICS {
+ text.push_str(&format!("- {}: {}\n", topic.name, topic.summary));
+ }
+ text
+}
+
+/// A heading line: its level and title, or `None` for any other line.
+fn heading_of(line: &str) -> Option<(usize, &str)> {
+ let level = line.bytes().take_while(|byte| *byte == b'#').count();
+ if !(1..=6).contains(&level) {
+ return None;
+ }
+ let title = line[level..].strip_prefix(' ')?;
+ Some((level, title.trim()))
+}
+
+/// The section under the heading titled `heading`: the heading line through
+/// the line before the next heading of the same or a higher level. Headings
+/// inside fenced code blocks (shell comments, for instance) are not headings.
+pub fn section<'a>(markdown: &'a str, heading: &str) -> Option<&'a str> {
+ let mut fence: Option<char> = None;
+ let mut start: Option<(usize, usize)> = None;
+ let mut offset = 0;
+ for line in markdown.split_inclusive('\n') {
+ let bare = line.trim_end_matches(['\n', '\r']);
+ let marker = bare.trim_start();
+ let opens = ["```", "~~~"]
+ .into_iter()
+ .find(|fence| marker.starts_with(fence))
+ .and_then(|fence| fence.chars().next());
+ match (fence, opens) {
+ (None, Some(open)) => fence = Some(open),
+ (Some(current), Some(close)) if current == close => fence = None,
+ _ => {}
+ }
+ if fence.is_none() && opens.is_none() {
+ if let Some((level, title)) = heading_of(bare) {
+ match start {
+ None if title == heading => start = Some((offset, level)),
+ Some((from, started)) if level <= started => {
+ return Some(markdown[from..offset].trim_end());
+ }
+ _ => {}
+ }
+ }
+ }
+ offset += line.len();
+ }
+ start.map(|(from, _)| markdown[from..].trim_end())
+}
+
+/// One line appended to the description of a tool that most often needs a
+/// guide, so an agent that never reads the skill still learns where to look.
+pub fn description_hint(tool: &str) -> Option<&'static str> {
+ Some(match tool {
+ "drag" => "Limits and fallbacks: `get_guide({topic:\"drag\"})`.",
+ "get_browser_state" | "browser_prepare" => {
+ "Setup and recovery: `get_guide({topic:\"browser\"})`."
+ }
+ "check_permissions" => "How to get them granted: `get_guide({topic:\"permissions\"})`.",
+ "run_steps" | "run_script" => "Batching rules: `get_guide({topic:\"batching\"})`.",
+ "invoke_menu" => "Menu paths and refusals: `get_guide({topic:\"menus\"})`.",
+ _ => return None,
+ })
+}
+
+#[derive(Deserialize)]
+struct GetGuideInput {
+ topic: Option<String>,
+}
+
+pub struct GetGuideTool;
+
+static DEF: OnceLock<ToolDef> = OnceLock::new();
+
+fn def() -> &'static ToolDef {
+ DEF.get_or_init(|| {
+ let topics = topic_names().join(", ");
+ ToolDef {
+ name: "get_guide".into(),
+ description: format!(
+ "Read Cua Driver guidance on demand, taken from the guide bundled with this \
+ driver (no skill install needed). Topics: {topics}. Call with no topic to list \
+ them. Read-only."
+ ),
+ input_schema: json!({
+ "type": "object",
+ "properties": {
+ "topic": {
+ "type": "string",
+ "description": format!("One of: {topics}. Omit to list the topics.")
+ }
+ },
+ "additionalProperties": false
+ }),
+ read_only: true,
+ destructive: false,
+ idempotent: true,
+ open_world: false,
+ }
+ })
+}
+
+#[async_trait]
+impl Tool for GetGuideTool {
+ fn def(&self) -> &ToolDef {
+ def()
+ }
+
+ async fn invoke(&self, args: Value) -> ToolResult {
+ let input = match parse_typed_input::<GetGuideInput>("get_guide", args) {
+ Ok(input) => input,
+ Err(result) => return result,
+ };
+ let names = topic_names();
+ let Some(topic) = input
+ .topic
+ .as_deref()
+ .map(str::trim)
+ .filter(|topic| !topic.is_empty())
+ else {
+ let topics: Vec<Value> = TOPICS
+ .iter()
+ .map(|topic| json!({"name": topic.name, "summary": topic.summary}))
+ .collect();
+ return ToolResult::text(index_text()).with_structured(json!({"topics": topics}));
+ };
+ match guide_for(topic, Platform::current()) {
+ Ok(guide) => {
+ let sources: Vec<Value> = guide
+ .sources
+ .iter()
+ .map(|(file, heading)| json!({"file": file, "heading": heading}))
+ .collect();
+ ToolResult::text(guide.text).with_structured(json!({
+ "topic": guide.topic,
+ "platform": guide.platform.label(),
+ "sources": sources,
+ "topics": names,
+ }))
+ }
+ Err(GuideError::UnknownTopic(topic)) => ToolResult::error(format!(
+ "get_guide: unknown topic {topic:?}. Topics: {}.",
+ names.join(", ")
+ ))
+ .with_structured(json!({
+ "code": "unknown_guide_topic",
+ "topic": topic,
+ "topics": names,
+ })),
+ Err(GuideError::MissingSection { file, heading }) => ToolResult::error(format!(
+ "get_guide: this build's {file} has no section {heading:?}. Read \
+ skill://cua-driver/{file} instead."
+ ))
+ .with_structured(json!({
+ "code": "guide_section_missing",
+ "file": file,
+ "heading": heading,
+ })),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::protocol::Content;
+
+ fn text_of(result: &ToolResult) -> String {
+ result
+ .content
+ .iter()
+ .filter_map(|content| match content {
+ Content::Text { text, .. } => Some(text.as_str()),
+ _ => None,
+ })
+ .collect::<Vec<_>>()
+ .join("\n")
+ }
+
+ async fn run(args: Value) -> ToolResult {
+ GetGuideTool.invoke(args).await
+ }
+
+ #[test]
+ fn every_topic_resolves_on_every_platform() {
+ for platform in Platform::ALL {
+ for name in topic_names() {
+ let guide = guide_for(name, platform)
+ .unwrap_or_else(|error| panic!("{name} on {platform:?}: {error:?}"));
+ assert!(
+ !guide.sources.is_empty(),
+ "{name} has no section on {platform:?}"
+ );
+ assert!(
+ guide.text.len() < 20_000,
+ "{name} on {platform:?} is {} bytes; split the topic instead of flooding the agent's context",
+ guide.text.len()
+ );
+ for (_, heading) in &guide.sources {
+ assert!(
+ guide.text.contains(heading),
+ "{name}: section {heading:?} missing from the text"
+ );
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn topics_return_the_guidance_an_agent_needs() {
+ let drag = guide_for("drag", Platform::Macos).unwrap().text;
+ assert!(drag.contains("drag_and_drop_session"));
+ assert!(drag.contains("`browser_pointer` `action:\"drag\"`"));
+ let windows_drag = guide_for("drag", Platform::Windows).unwrap().text;
+ assert!(windows_drag.contains("Drag / drag-and-drop"));
+ assert!(windows_drag.contains("WPF drags"));
+ assert!(!windows_drag.contains("drag_and_drop_session"));
+ assert!(guide_for("browser", Platform::Linux)
+ .unwrap()
+ .text
+ .contains("browser_prepare"));
+ let permissions = guide_for("permissions", Platform::Macos).unwrap().text;
+ assert!(permissions.contains("Install and approve permissions"));
+ assert!(permissions.contains("Screen Recording"));
+ let batching = guide_for("batching", Platform::Windows).unwrap().text;
+ assert!(batching.contains("run_steps") && batching.contains("run_script"));
+ assert!(guide_for("menus", Platform::Macos)
+ .unwrap()
+ .text
+ .contains("invoke_menu"));
+ assert!(guide_for("menus", Platform::Linux)
+ .unwrap()
+ .text
+ .contains("AT-SPI"));
+ let overview = guide_for("overview", Platform::Linux).unwrap().text;
+ assert!(overview.contains("## Efficient loop"));
+ assert!(
+ !overview.contains("x-release-please-version"),
+ "the overview is the body, not the frontmatter"
+ );
+ }
+
+ #[test]
+ fn a_topic_reads_only_the_hosts_platform_guide() {
+ let macos = guide_for("permissions", Platform::Macos).unwrap();
+ assert!(macos.sources.iter().all(|(file, _)| *file == "MACOS.md"));
+ let linux = guide_for("permissions", Platform::Linux).unwrap();
+ assert!(linux.sources.iter().all(|(file, _)| *file == "LINUX.md"));
+ assert!(!linux.text.contains("MACOS.md ==="));
+ }
+
+ #[test]
+ fn topic_names_are_case_and_space_insensitive() {
+ assert_eq!(guide_for(" Drag ", Platform::Macos).unwrap().topic, "drag");
+ }
+
+ #[tokio::test]
+ async fn unknown_topic_is_an_error_that_lists_the_topics() {
+ assert_eq!(
+ guide_for("nonsense", Platform::Macos).unwrap_err(),
+ GuideError::UnknownTopic("nonsense".into())
+ );
+ let result = run(json!({"topic": "nonsense"})).await;
+ assert_eq!(result.is_error, Some(true));
+ let message = text_of(&result);
+ for name in topic_names() {
+ assert!(message.contains(name), "{message}");
+ }
+ assert!(message.contains("nonsense"));
+ let structured = result.structured_content.unwrap();
+ assert_eq!(structured["code"], "unknown_guide_topic");
+ assert_eq!(structured["topics"], json!(topic_names()));
+ }
+
+ #[tokio::test]
+ async fn no_topic_lists_every_topic() {
+ for args in [json!({}), json!({"topic": ""}), json!({"topic": " "})] {
+ let result = run(args).await;
+ assert_ne!(result.is_error, Some(true));
+ let text = text_of(&result);
+ for name in topic_names() {
+ assert!(text.contains(&format!("- {name}:")), "{text}");
+ }
+ }
+ }
+
+ #[tokio::test]
+ async fn the_tool_returns_a_guide_with_its_sources() {
+ let result = run(json!({"topic": "batching"})).await;
+ assert_ne!(result.is_error, Some(true));
+ let text = text_of(&result);
+ assert!(text.starts_with("Cua Driver guide: batching"));
+ assert!(text.contains("skill://cua-driver/WORKFLOW.md"));
+ let structured = result.structured_content.unwrap();
+ assert_eq!(structured["topic"], "batching");
+ assert_eq!(structured["sources"][0]["file"], "WORKFLOW.md");
+ }
+
+ #[test]
+ fn the_tool_is_read_only_and_describes_every_topic() {
+ let def = def();
+ assert!(def.read_only && !def.destructive && def.idempotent && !def.open_world);
+ for name in topic_names() {
+ assert!(def.description.contains(name));
+ }
+ }
+
+ #[test]
+ fn section_stops_at_the_next_heading_of_the_same_or_higher_level() {
+ let doc = "# T\n\n## A\none\n### A1\ntwo\n## B\nthree\n";
+ assert_eq!(section(doc, "A"), Some("## A\none\n### A1\ntwo"));
+ assert_eq!(section(doc, "A1"), Some("### A1\ntwo"));
+ assert_eq!(section(doc, "B"), Some("## B\nthree"));
+ assert_eq!(section(doc, "T"), Some(doc.trim_end()));
+ assert_eq!(section(doc, "Missing"), None);
+ }
+
+ #[test]
+ fn section_ignores_headings_inside_code_fences() {
+ let doc = "## A\n```bash\n# not a heading\n## nor this\n```\nafter\n## B\n";
+ assert_eq!(
+ section(doc, "A"),
+ Some("## A\n```bash\n# not a heading\n## nor this\n```\nafter")
+ );
+ assert_eq!(section(doc, "nor this"), None);
+ let tilde = "## A\n~~~\n## x\n~~~\n## B\n";
+ assert_eq!(section(tilde, "A"), Some("## A\n~~~\n## x\n~~~"));
+ }
+
+ #[test]
+ fn hinted_tools_name_a_real_topic() {
+ for tool in [
+ "drag",
+ "get_browser_state",
+ "browser_prepare",
+ "check_permissions",
+ "run_steps",
+ "run_script",
+ "invoke_menu",
+ ] {
+ let hint = description_hint(tool).unwrap_or_else(|| panic!("{tool} has no hint"));
+ let topic = hint
+ .split("topic:\"")
+ .nth(1)
+ .and_then(|rest| rest.split('"').next())
+ .unwrap_or_else(|| panic!("{hint}"));
+ assert!(topic_names().contains(&topic), "{tool}: {hint}");
+ }
+ assert_eq!(description_hint("click"), None);
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs
index 5ab1462c59..611b058030 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs
@@ -10,6 +10,7 @@
// here would churn every adapter's call sites for no runtime gain.
#![allow(clippy::result_large_err)]
+pub mod guide;
pub mod mcp_skills;
pub mod mcp_wire;
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/mcp_skills.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/mcp_skills.rs
index a370d51c31..02245026f8 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/mcp_skills.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/mcp_skills.rs
@@ -61,6 +61,20 @@ const FILES: &[(&str, &str)] = &[
),
];
+/// The compiled-in skill files as `(file name, text)`. The same bytes back
+/// the MCP resources, the `get_guide` tool and the offline skill installer, so
+/// all three always match this binary.
+pub fn embedded_files() -> &'static [(&'static str, &'static str)] {
+ FILES
+}
+
+/// One compiled-in skill file by its name (for example `MACOS.md`).
+pub fn embedded_file(name: &str) -> Option<&'static str> {
+ FILES
+ .iter()
+ .find_map(|(file, text)| (*file == name).then_some(*text))
+}
+
struct Pack {
entry: Value,
resources: Vec<Value>,
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs
index 1b08205223..63733f8950 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs
@@ -361,17 +361,18 @@ pub fn initialize_result() -> Value {
/// Goose uses in its `ComputerController` extension and Open
/// Interpreter uses for its system message.
fn agent_instructions() -> String {
+ // macOS needs no platform pointer: its permission line below names MACOS.md.
let (tree_kind, platform_skill_pointer) = if cfg!(target_os = "macos") {
- ("AX (Accessibility)", "MACOS.md (permissions)")
+ ("AX", "")
} else if cfg!(target_os = "windows") {
(
- "UIA (UI Automation)",
- "WINDOWS.md (UIA tree, UWP/ApplicationFrameHost hosting, Session 0 isolation)",
+ "UIA",
+ ", WINDOWS.md (UIA tree, UWP/ApplicationFrameHost hosting, Session 0 isolation)",
)
} else {
(
"AT-SPI",
- "LINUX.md (X11/Wayland status, AT-SPI bus, BETA-level support)",
+ ", LINUX.md (X11/Wayland status, AT-SPI bus, BETA-level support)",
)
};
@@ -400,7 +401,7 @@ fn agent_instructions() -> String {
1. `list_windows({{app:"Name"}})` or `launch_app` for `pid` and `window_id`.
2. Read narrowly: `get_window_state` with `query:"Save"`. Re-read with `since:"latest"`.
-3. Act by `element_token` ({tree_kind}): row `[N]` is `<snapshot_id>:N`. Pixel `x,y` only for surfaces missing from the tree.
+3. Act by `element_token` ({tree_kind}): row `[N]` is `<snapshot_id>:N`. Pixels only for surfaces missing from the tree.
4. Act through `run_steps({{steps:[{{tool,args}}],observe:{{}}}})`, even for one step: stops at the first failure, returns what changed.{script_line}
5. Verify at checkpoints, not after every action: `verify_state(pid, window_id, expect)`. `unknown` and `effect:"unverifiable"` are not success.
@@ -410,7 +411,7 @@ Chrome/Edge/Brave page: `get_browser_state({{pid, window_id}})`, its `detail.nex
`start_session` is optional; repeat a short `session` label on every call that accepts it. On continuation/recent-work, call `history_status`; if ready, make one bounded initial `history_query` before broad discovery.{permission_line}
-Details: `skill://cua-driver/SKILL.md` and {platform_skill_pointer}."#
+Guides: `get_guide({{topic}})` (drag, browser, permissions, batching, menus), `skill://cua-driver/SKILL.md`{platform_skill_pointer}."#
)
}
@@ -533,6 +534,23 @@ mod agent_instruction_tests {
);
}
+ #[test]
+ fn instructions_point_at_get_guide_and_keep_the_skill_resource() {
+ let instructions = agent_instructions();
+ assert!(instructions.contains("`get_guide({topic})`"));
+ for topic in crate::guide::topic_names()
+ .into_iter()
+ .filter(|topic| *topic != "overview")
+ {
+ assert!(
+ instructions.contains(topic),
+ "instructions should name the {topic} topic"
+ );
+ }
+ assert!(instructions.contains("`skill://cua-driver/SKILL.md`"));
+ assert!(instructions.split_whitespace().count() <= 200);
+ }
+
#[test]
fn macos_instructions_gate_permission_approval_on_owner_authorization() {
let instructions = agent_instructions();
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs
index 4ef4e462d8..76dcbf27a1 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs
@@ -166,9 +166,15 @@ impl ToolDef {
let input_schema = advertised_runtime_input_schema(&self.name, &self.input_schema);
let caps = advertised_capabilities_for(&self.name, &input_schema);
let risk = crate::authorization::risk_metadata_json(&self.name);
+ // Tools that most often need a guide point at `get_guide`, so an agent
+ // that never reads the skill still learns where the guidance lives.
+ let description = match crate::guide::description_hint(&self.name) {
+ Some(hint) => format!("{} {hint}", self.description),
+ None => self.description.clone(),
+ };
let mut entry = serde_json::json!({
"name": self.name,
- "description": self.description,
+ "description": description,
"inputSchema": input_schema,
"annotations": {
"readOnlyHint": self.read_only,
@@ -700,7 +706,7 @@ fn deprecated_name_note(old: &str, new: &str) -> String {
/// - `browser.state`, `browser.prepare`, `browser.navigate`,
/// `browser.input.click`, `browser.input.type`, `browser.input.files`,
/// `browser.dialog`
-/// - `driver.update_check`, `driver.probe`
+/// - `driver.update_check`, `driver.guide`, `driver.probe`
/// - `history.status`, `history.query`
///
/// Tools with no entry get `[]` — that's fine, it just means
@@ -845,6 +851,7 @@ pub fn default_capabilities_for(tool_name: &str) -> Vec<String> {
// ── driver self-service ──────────────────────────────────────
"check_for_update" => &["driver.update_check"],
+ "get_guide" => &["driver.guide"],
"probe" => &["driver.probe"],
// ── encrypted local Computer History ─────────────────────────
@@ -1361,6 +1368,7 @@ impl ToolRegistry {
self.register(Box::new(ListSessionsTool));
self.register(Box::new(GetSessionStateTool));
self.register(Box::new(EndSessionTool));
+ self.register(Box::new(crate::guide::GetGuideTool));
self.register_batch_tools();
}
@@ -3472,6 +3480,7 @@ fn session_requiring_tool(tool_name: &str) -> bool {
tool_name,
"check_permissions"
| "health_report"
+ | "get_guide"
| "get_session"
| "list_sessions"
| "get_session_state"
@@ -6433,6 +6442,7 @@ mod capability_tests {
// misc
"page",
"check_for_update",
+ "get_guide",
"probe",
// browser-tool v1
"get_browser_state",
@@ -6539,6 +6549,7 @@ mod capability_tests {
"browser.input.pointer",
// driver self
"driver.update_check",
+ "driver.guide",
"driver.probe",
// encrypted local history
"history.status",
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/tests/get_guide_tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/tests/get_guide_tool.rs
new file mode 100644
index 0000000000..37367100db
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/tests/get_guide_tool.rs
@@ -0,0 +1,157 @@
+//! `get_guide` through the real registry: listed, callable without a session,
+//! closed to unknown arguments, and pointed at from the tools that need it.
+
+use cua_driver_core::protocol::{Content, ToolResult};
+use cua_driver_core::tool::{Tool, ToolDef, ToolRegistry};
+use serde_json::{json, Value};
+
+struct Stub(ToolDef);
+
+#[async_trait::async_trait]
+impl Tool for Stub {
+ fn def(&self) -> &ToolDef {
+ &self.0
+ }
+
+ async fn invoke(&self, _args: Value) -> ToolResult {
+ ToolResult::text("stub")
+ }
+}
+
+fn stub(name: &str, description: &str) -> Box<dyn Tool> {
+ Box::new(Stub(ToolDef {
+ name: name.into(),
+ description: description.into(),
+ input_schema: json!({"type": "object", "properties": {}}),
+ read_only: false,
+ destructive: false,
+ idempotent: false,
+ open_world: false,
+ }))
+}
+
+fn registry() -> ToolRegistry {
+ let mut registry = ToolRegistry::new();
+ registry.register_session_tools();
+ registry
+}
+
+fn text_of(result: &ToolResult) -> String {
+ result
+ .content
+ .iter()
+ .filter_map(|content| match content {
+ Content::Text { text, .. } => Some(text.as_str()),
+ _ => None,
+ })
+ .collect::<Vec<_>>()
+ .join("\n")
+}
+
+fn entry(list: &Value, name: &str) -> Value {
+ list["tools"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|tool| tool["name"] == name)
+ .unwrap_or_else(|| panic!("{name} is not listed"))
+ .clone()
+}
+
+#[test]
+fn get_guide_is_listed_as_a_read_only_tool_that_names_its_topics() {
+ let list = registry().tools_list();
+ let tool = entry(&list, "get_guide");
+ assert_eq!(tool["annotations"]["readOnlyHint"], true);
+ assert_eq!(tool["annotations"]["destructiveHint"], false);
+ assert_eq!(tool["annotations"]["openWorldHint"], false);
+ let description = tool["description"].as_str().unwrap();
+ for topic in ["drag", "browser", "permissions", "batching", "menus"] {
+ assert!(description.contains(topic), "{description}");
+ }
+ assert_eq!(tool["inputSchema"]["additionalProperties"], false);
+ assert!(tool["inputSchema"]["properties"]["topic"].is_object());
+}
+
+#[tokio::test]
+async fn an_agent_with_no_skill_installed_can_fetch_a_guide_by_tool_call() {
+ let registry = registry();
+ for topic in ["drag", "browser", "permissions", "batching", "menus"] {
+ let result = registry.invoke("get_guide", json!({"topic": topic})).await;
+ assert_ne!(result.is_error, Some(true), "{topic}: {result:?}");
+ let text = text_of(&result);
+ assert!(
+ text.starts_with(&format!("Cua Driver guide: {topic}")),
+ "{text}"
+ );
+ assert!(text.len() > 500, "{topic} returned almost nothing");
+ assert_eq!(result.structured_content.unwrap()["topic"], topic);
+ }
+}
+
+#[tokio::test]
+async fn an_unknown_topic_is_an_error_naming_the_valid_topics() {
+ let result = registry()
+ .invoke("get_guide", json!({"topic": "teleportation"}))
+ .await;
+ assert_eq!(result.is_error, Some(true));
+ let message = text_of(&result);
+ assert!(message.contains("teleportation"), "{message}");
+ for topic in ["drag", "browser", "permissions", "batching", "menus"] {
+ assert!(message.contains(topic), "{message}");
+ }
+ assert_eq!(
+ result.structured_content.unwrap()["code"],
+ "unknown_guide_topic"
+ );
+}
+
+#[tokio::test]
+async fn no_topic_lists_the_topics_and_unknown_arguments_are_refused() {
+ let registry = registry();
+ let listed = registry.invoke("get_guide", json!({})).await;
+ assert_ne!(listed.is_error, Some(true));
+ assert!(text_of(&listed).contains("- drag:"));
+ let refused = registry
+ .invoke("get_guide", json!({"topic": "drag", "section": "x"}))
+ .await;
+ assert_eq!(refused.is_error, Some(true), "{refused:?}");
+}
+
+#[test]
+fn tools_that_most_need_a_guide_point_at_it() {
+ let mut registry = registry();
+ for tool in [
+ "drag",
+ "get_browser_state",
+ "browser_prepare",
+ "check_permissions",
+ "invoke_menu",
+ ] {
+ registry.register(stub(tool, "Does the thing."));
+ }
+ registry.register(stub("click", "Clicks."));
+ let list = registry.tools_list();
+ let described = |name: &str| {
+ entry(&list, name)["description"]
+ .as_str()
+ .unwrap()
+ .to_owned()
+ };
+ for (tool, topic) in [
+ ("drag", "drag"),
+ ("get_browser_state", "browser"),
+ ("browser_prepare", "browser"),
+ ("check_permissions", "permissions"),
+ ("invoke_menu", "menus"),
+ ("run_steps", "batching"),
+ ] {
+ assert!(
+ described(tool).contains(&format!("get_guide({{topic:\"{topic}\"}})")),
+ "{tool}: {}",
+ described(tool)
+ );
+ }
+ assert_eq!(described("click"), "Clicks.");
+ assert!(described("drag").starts_with("Does the thing. "));
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
index c76f074604..7f27daa1d8 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -48,6 +48,8 @@ pub enum Command {
},
McpConfig {
client: Option<String>,
+ /// Skip installing the skill pack for `client` (`--no-skills`).
+ no_skills: bool,
},
Serve {
socket: Option<String>,
@@ -843,7 +845,10 @@ pub fn parse_command() -> Command {
grants: grants.clone(),
},
Some("list-tools") => Command::ListTools,
- Some("mcp-config") => Command::McpConfig { client: mcp_client },
+ Some("mcp-config") => Command::McpConfig {
+ client: mcp_client,
+ no_skills: args.iter().any(|a| a == "--no-skills"),
+ },
Some("serve") => Command::Serve {
socket,
pid_file: flag_value(&args, "--pid-file"),
@@ -2083,8 +2088,11 @@ pub fn build_manifest() -> serde_json::Value {
{ "name": "--socket", "type": "string", "description": "Override the required daemon socket path." }
] },
{ "name": "mcp-config",
- "description": "Print client-specific connection guidance (MCP config where supported).",
- "args": [ { "name": "--client", "type": "string", "description": "One of: claude, codex, cursor, hermes, antigravity, openclaw, opencode, pi, prime-agent, qwen, droid, zcode. Omit for the generic snippet." } ] },
+ "description": "Print client-specific connection guidance (MCP config where supported) and, with --client, install the skill pack for that agent.",
+ "args": [
+ { "name": "--client", "type": "string", "description": "One of: claude, codex, cursor, hermes, antigravity, openclaw, opencode, pi, prime-agent, qwen, droid, zcode. Omit for the generic snippet." },
+ { "name": "--no-skills", "type": "flag", "description": "With --client, do not install the cua-driver skill pack for that agent." }
+ ] },
{ "name": "manifest",
"description": "Emit this machine-readable description of the CLI surface.",
"args": [ { "name": "--pretty", "type": "flag", "description": "Pretty-print the JSON." } ] },
@@ -2208,7 +2216,14 @@ pub fn build_manifest() -> serde_json::Value {
/// `--client <name>` selects one of: claude, codex, cursor, hermes,
/// antigravity, openclaw, opencode, pi, prime-agent, qwen, droid, zcode.
/// Omit for the generic JSON snippet.
-pub fn run_mcp_config(client: Option<&str>) {
+///
+/// A named client also gets the skill pack for its agent, because agents
+/// connected over MCP rarely read the skill resource on their own. One line
+/// on stderr (stdout stays the pasteable config) says where it went; pass
+/// `no_skills` (`--no-skills`) to leave the agent's skills folder alone. Only a
+/// failure to print the config exits nonzero: a skill pack that cannot be
+/// installed is reported and does not fail the command.
+pub fn run_mcp_config(client: Option<&str>, no_skills: bool) {
let binary = std::env::current_exe()
.ok()
.and_then(|p| p.to_str().map(str::to_owned))
@@ -2438,6 +2453,15 @@ pub fn run_mcp_config(client: Option<&str>) {
process::exit(2);
}
}
+
+ // A client that got past the match above is a known one.
+ if let Some(client) = client.filter(|client| !client.is_empty()) {
+ if !no_skills {
+ if let Some(line) = crate::skills::install_for_client_line(client) {
+ eprintln!("{line}");
+ }
+ }
+ }
}
/// Invoke a tool through the required running daemon. Prints result to stdout
@@ -4499,11 +4523,11 @@ fn cli_docs_literal() -> serde_json::Value {
},
{
"name": "mcp-config",
- "abstract": "Print client-specific connection guidance (MCP config where supported).",
- "discussion": "Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode.",
+ "abstract": "Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.",
+ "discussion": "Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.",
"arguments": no_args,
"options": [{"name":"client","short_name":null,"help":"Client name to print configuration for.","type":"String","default_value":null,"is_optional":true}],
- "flags": no_flags,
+ "flags": [{"name":"no-skills","short_name":null,"help":"With --client, do not install the cua-driver skill pack for that agent.","default_value":false}],
"subcommands": no_subcommands
},
{
@@ -4790,7 +4814,8 @@ const CLI_EXAMPLES: &[(&str, &[(&str, &str)])] = &[
("permissions grant", &[("cua-driver permissions grant", "Request the grants for CuaDriver.app")]),
("mcp-config", &[
("cua-driver mcp-config", "Print a generic mcpServers entry"),
- ("cua-driver mcp-config --client codex", "Print setup for Codex"),
+ ("cua-driver mcp-config --client codex", "Print setup for Codex and install its skill pack"),
+ ("cua-driver mcp-config --client codex --no-skills", "Print setup for Codex only"),
]),
("recording", &[("cua-driver recording", "Print the current recording state")]),
("recording start", &[("cua-driver recording start ~/cua-trajectories/demo1", "Record turns into a directory")]),
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
index 6636979ee0..2dc89ef221 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
@@ -556,8 +556,8 @@ fn main() {
let tools = inspect_tools_without_runtime();
cli::run_describe(&tools, &name);
}
- cli::Command::McpConfig { client } => {
- cli::run_mcp_config(client.as_deref());
+ cli::Command::McpConfig { client, no_skills } => {
+ cli::run_mcp_config(client.as_deref(), no_skills);
}
cli::Command::Manifest { pretty } => {
// Surface 8: machine-readable CLI manifest. Read-only — no
@@ -977,8 +977,8 @@ fn main() -> anyhow::Result<()> {
cli::run_describe(&tools, &name);
Ok(())
}
- cli::Command::McpConfig { client } => {
- cli::run_mcp_config(client.as_deref());
+ cli::Command::McpConfig { client, no_skills } => {
+ cli::run_mcp_config(client.as_deref(), no_skills);
Ok(())
}
cli::Command::Manifest { pretty } => {
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
index 48a0a87637..3ffeed26a9 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
@@ -1,12 +1,15 @@
//! `cua-driver skills {install|update|uninstall|status|path}` —
//! agent skill-pack management.
//!
-//! The install scripts intentionally do NOT touch the user's
+//! The binary install scripts intentionally do NOT touch the user's
//! `~/.claude/skills/` (etc.) directories — too invasive for an
//! `irm | iex` / `curl | sh` one-liner that the user might be running
-//! just to try the binary. This verb is the opt-in path: fetch the
-//! versioned skill pack from a matching GitHub release and symlink it
-//! into each detected agent's skills dir.
+//! just to try the binary. Wiring up an agent is the explicit step:
+//! `cua-driver mcp-config --client <agent>` installs the skill pack for
+//! that agent by default (`--no-skills` opts out; see
+//! [`install_for_client`]), and this verb installs it for every detected
+//! agent: fetch the versioned skill pack from a matching GitHub release and
+//! symlink it into each detected agent's skills dir.
//!
//! ## Subcommands
//!
@@ -42,6 +45,7 @@
//!
//! - Claude Code: `~/.claude/skills/`
//! - Codex: `~/.agents/skills/`
+//! - Cursor: `~/.agents/skills/` (shared with Codex and Pi; Cursor also reads `~/.claude/skills/`)
//! - Pi: `~/.agents/skills/` (shared global location; Pi also reads `~/.pi/agent/skills/`)
//! - Prime Agent: `~/.prime/agent/skills/`
//! - OpenClaw: `~/.openclaw/skills/`
@@ -226,6 +230,13 @@ const AGENTS: &[Agent] = &[
parent: AgentParent::Home(".agents/skills"),
install_marker: Some(".pi/agent"),
},
+ Agent {
+ label: "Cursor",
+ // Cursor loads ~/.agents/skills too. Reuse it so Cursor, Codex and Pi
+ // converge on one managed cua-driver link.
+ parent: AgentParent::Home(".agents/skills"),
+ install_marker: Some(".cursor"),
+ },
Agent {
label: "Prime Agent",
parent: AgentParent::Home(".prime/agent/skills"),
@@ -580,6 +591,18 @@ fn link_agent_paths(
parent: &Path,
install_marker: Option<&Path>,
local_skill_dir: &Path,
+) -> Result<LinkStatus> {
+ link_agent_paths_with(agent_label, parent, install_marker, local_skill_dir, true)
+}
+
+/// [`link_agent_paths`] with the progress lines switched off for callers whose
+/// stdout carries something else (`mcp-config`).
+fn link_agent_paths_with(
+ agent_label: &str,
+ parent: &Path,
+ install_marker: Option<&Path>,
+ local_skill_dir: &Path,
+ chatty: bool,
) -> Result<LinkStatus> {
if !ensure_skills_parent(parent, install_marker)? {
return Ok(LinkStatus::NotDetected);
@@ -598,11 +621,13 @@ fn link_agent_paths(
let has_metadata = link.symlink_metadata().is_ok();
let resolves = link.exists();
if has_metadata && resolves {
- println!(
- " {} skill link already exists at {} (skipping)",
- agent_label,
- link.display()
- );
+ if chatty {
+ println!(
+ " {} skill link already exists at {} (skipping)",
+ agent_label,
+ link.display()
+ );
+ }
return Ok(LinkStatus::Existing);
}
if has_metadata && !resolves && is_symlink_or_junction(&link) {
@@ -610,18 +635,22 @@ fn link_agent_paths(
// sweep_legacy_skill_pack cleaned a pre-rename pack out from
// under it). Remove + recreate pointing at the new target.
if let Err(e) = remove_link(&link) {
- eprintln!(
- " warning: could not remove stale {} link at {}: {e}",
+ if chatty {
+ eprintln!(
+ " warning: could not remove stale {} link at {}: {e}",
+ agent_label,
+ link.display()
+ );
+ }
+ return Ok(LinkStatus::Existing);
+ }
+ if chatty {
+ println!(
+ " cleaned up stale {} link at {}",
agent_label,
link.display()
);
- return Ok(LinkStatus::Existing);
}
- println!(
- " cleaned up stale {} link at {}",
- agent_label,
- link.display()
- );
}
make_dir_symlink(local_skill_dir, &link).with_context(|| {
format!(
@@ -630,7 +659,9 @@ fn link_agent_paths(
local_skill_dir.display()
)
})?;
- println!(" ✅ linked {} skill at {}", agent_label, link.display());
+ if chatty {
+ println!(" ✅ linked {} skill at {}", agent_label, link.display());
+ }
Ok(LinkStatus::Created)
}
@@ -660,6 +691,155 @@ fn make_dir_symlink(target: &Path, link: &Path) -> Result<()> {
Ok(())
}
+// ── default install for `mcp-config --client <agent>` ─────────────────────
+
+/// The agents whose skills directory `cua-driver mcp-config --client <client>`
+/// installs the skill pack into. A client with no known skills directory
+/// (Qwen Code, Factory Droid, ZCode) maps to none.
+fn client_agents(client: &str) -> Vec<Agent> {
+ let labels: &[&str] = match client {
+ "claude" | "claude-code" => &["Claude Code"],
+ "codex" => &["Codex"],
+ "cursor" => &["Cursor"],
+ "openclaw" => &["OpenClaw"],
+ "opencode" => &["OpenCode"],
+ "hermes" => &["Hermes"],
+ "antigravity" | "gemini" => &["Antigravity IDE", "Antigravity CLI"],
+ "pi" => &["Pi"],
+ "prime-agent" => &["Prime Agent"],
+ _ => &[],
+ };
+ AGENTS
+ .iter()
+ .filter(|agent| labels.contains(&agent.label))
+ .copied()
+ .collect()
+}
+
+/// How one `mcp-config --client` run left the skill pack.
+#[derive(Debug, PartialEq, Eq)]
+pub enum ClientSkills {
+ /// The client has no skills directory to install into.
+ Unsupported,
+ /// Linked for these agents; `true` when this run created the link.
+ Installed(Vec<(&'static str, PathBuf, bool)>),
+ /// The client's own folder is not on this computer yet.
+ NotFound(Vec<&'static str>),
+}
+
+/// Install the skill pack for the agent behind `cua-driver mcp-config
+/// --client <client>`, the default when that command wires up an agent.
+///
+/// The pack is the one compiled into this binary, so it matches the driver the
+/// agent is about to start and needs no network. It lands where the explicit
+/// `skills install` puts it: a local copy under `<HomeDir>/skills/cua-driver`
+/// and a link to it from the agent's skills directory. The agent was named on
+/// the command line, so its skills directory is created when the agent's own
+/// folder (`~/.claude`, `~/.config/opencode`, ...) exists. A link or folder
+/// that is already there is never replaced, and nothing goes to stdout.
+pub fn install_for_client(client: &str) -> Result<ClientSkills> {
+ let agents = client_agents(client);
+ if agents.is_empty() {
+ return Ok(ClientSkills::Unsupported);
+ }
+ let local = local_skill_dir()?;
+ let mut staged = false;
+ let mut installed = Vec::new();
+ let mut missing = Vec::new();
+ for agent in agents {
+ let parent = agent.parent_path()?;
+ let marker = agent
+ .install_marker_path()?
+ .filter(|marker| marker.is_dir())
+ .or_else(|| parent.parent().map(Path::to_path_buf));
+ if !(parent.is_dir() || marker.as_deref().is_some_and(Path::is_dir)) {
+ missing.push(agent.label);
+ continue;
+ }
+ if !staged {
+ stage_embedded(&local)?;
+ staged = true;
+ }
+ match link_agent_paths_with(agent.label, &parent, marker.as_deref(), &local, false)? {
+ LinkStatus::Created => {
+ installed.push((agent.label, parent.join(SKILL_PACK_NAME), true))
+ }
+ LinkStatus::Existing => {
+ installed.push((agent.label, parent.join(SKILL_PACK_NAME), false))
+ }
+ LinkStatus::NotDetected => missing.push(agent.label),
+ }
+ }
+ Ok(if installed.is_empty() {
+ ClientSkills::NotFound(missing)
+ } else {
+ ClientSkills::Installed(installed)
+ })
+}
+
+/// Write the skill files compiled into this binary to `dest`, host platform
+/// only, changing only files whose content differs. A `dest` that is itself a
+/// link is somebody's checkout (a developer's hand-rolled setup): leave it be.
+fn stage_embedded(dest: &Path) -> Result<()> {
+ if is_symlink_or_junction(dest) {
+ return Ok(());
+ }
+ fs::create_dir_all(dest).with_context(|| format!("create {}", dest.display()))?;
+ for (name, text) in cua_driver_core::mcp_skills::embedded_files() {
+ if is_excluded_platform_doc(name, false) {
+ continue;
+ }
+ let path = dest.join(name);
+ if fs::read_to_string(&path).is_ok_and(|current| current == *text) {
+ continue;
+ }
+ fs::write(&path, text).with_context(|| format!("write {}", path.display()))?;
+ }
+ Ok(())
+}
+
+/// The one line `mcp-config --client <client>` prints (to stderr, so the
+/// config on stdout stays pasteable) about the skill pack, or `None` when the
+/// client has no skills directory.
+pub fn install_for_client_line(client: &str) -> Option<String> {
+ client_skills_line(client, install_for_client(client))
+}
+
+fn client_skills_line(client: &str, outcome: Result<ClientSkills>) -> Option<String> {
+ match outcome {
+ Ok(ClientSkills::Unsupported) => None,
+ Ok(ClientSkills::Installed(links)) => {
+ let names = links
+ .iter()
+ .map(|(label, _, _)| *label)
+ .collect::<Vec<_>>()
+ .join(", ");
+ let paths = links
+ .iter()
+ .map(|(_, path, _)| path.display().to_string())
+ .collect::<Vec<_>>()
+ .join(", ");
+ Some(if links.iter().all(|(_, _, created)| !created) {
+ format!("cua-driver: the skill pack for {names} is already installed at {paths}.")
+ } else {
+ format!(
+ "cua-driver: installed the skill pack for {names} at {paths} \
+ (skip with --no-skills, remove with `cua-driver skills uninstall`)."
+ )
+ })
+ }
+ Ok(ClientSkills::NotFound(labels)) => Some(format!(
+ "cua-driver: no {} folder found yet, so the skill pack was not installed. \
+ Run `cua-driver skills install` once the agent has started.",
+ labels.join(" or ")
+ )),
+ Err(error) => Some(format!(
+ "cua-driver: could not install the skill pack for {client}: {error:#}. \
+ Run `cua-driver skills install` to retry."
+ )),
+ }
+}
+
// ── fetch ──────────────────────────────────────────────────────────────────
fn fetch_into(dest: &Path, from_main: bool, all_platforms: bool) -> Result<()> {
@@ -955,10 +1135,12 @@ fn print_path() -> Result<()> {
#[cfg(test)]
mod tests {
use super::{
- ensure_skills_parent, extract_tar_gz, link_agent_paths, resolve_hermes_skills_dir,
- skill_release_url, unix_hermes_home, windows_hermes_home, AgentParent, LinkStatus, AGENTS,
+ client_agents, client_skills_line, ensure_skills_parent, extract_tar_gz, link_agent_paths,
+ link_agent_paths_with, resolve_hermes_skills_dir, skill_release_url, stage_embedded,
+ unix_hermes_home, windows_hermes_home, AgentParent, ClientSkills, LinkStatus, AGENTS,
SKILL_FILES,
};
+ use anyhow::anyhow;
use std::path::PathBuf;
use tempfile::tempdir;
@@ -1097,6 +1279,161 @@ mod tests {
assert!(parent.join("cua-driver").exists());
}
+ #[test]
+ fn cursor_shares_the_codex_and_pi_skill_directory() {
+ let cursor = AGENTS.iter().find(|agent| agent.label == "Cursor").unwrap();
+ assert!(matches!(cursor.parent, AgentParent::Home(".agents/skills")));
+ assert!(matches!(cursor.install_marker, Some(".cursor")));
+ }
+
+ #[test]
+ fn every_mcp_config_client_with_a_skills_folder_maps_to_its_agents() {
+ let labels = |client: &str| -> Vec<&'static str> {
+ client_agents(client)
+ .into_iter()
+ .map(|agent| agent.label)
+ .collect()
+ };
+ assert_eq!(labels("claude"), ["Claude Code"]);
+ assert_eq!(labels("claude-code"), ["Claude Code"]);
+ assert_eq!(labels("codex"), ["Codex"]);
+ assert_eq!(labels("cursor"), ["Cursor"]);
+ assert_eq!(labels("openclaw"), ["OpenClaw"]);
+ assert_eq!(labels("opencode"), ["OpenCode"]);
+ assert_eq!(labels("hermes"), ["Hermes"]);
+ assert_eq!(labels("pi"), ["Pi"]);
+ assert_eq!(labels("prime-agent"), ["Prime Agent"]);
+ assert_eq!(
+ labels("antigravity"),
+ ["Antigravity IDE", "Antigravity CLI"]
+ );
+ assert_eq!(labels("gemini"), labels("antigravity"));
+ // No skills folder is known for these.
+ for client in [
+ "qwen",
+ "qwen-code",
+ "droid",
+ "factory",
+ "zcode",
+ "",
+ "emacs",
+ ] {
+ assert!(labels(client).is_empty(), "{client}");
+ }
+ }
+
+ #[test]
+ fn quiet_linking_reports_the_same_status_without_printing() {
+ let home = tempdir().unwrap();
+ let parent = home.path().join(".claude/skills");
+ let marker = home.path().join(".claude");
+ let local_skill = home.path().join("pack");
+ std::fs::create_dir_all(&marker).unwrap();
+ std::fs::create_dir_all(&local_skill).unwrap();
+ assert_eq!(
+ link_agent_paths_with("Claude Code", &parent, Some(&marker), &local_skill, false)
+ .unwrap(),
+ LinkStatus::Created
+ );
+ assert_eq!(
+ link_agent_paths_with("Claude Code", &parent, Some(&marker), &local_skill, false)
+ .unwrap(),
+ LinkStatus::Existing
+ );
+ }
+
+ #[test]
+ fn the_staged_pack_is_the_embedded_pack_for_this_host_only() {
+ let root = tempdir().unwrap();
+ let stage = root.path().join("skills/cua-driver");
+ stage_embedded(&stage).unwrap();
+ for (name, text) in cua_driver_core::mcp_skills::embedded_files() {
+ let other_platform = ["WINDOWS.md", "MACOS.md", "LINUX.md"].contains(name)
+ && !name.eq_ignore_ascii_case(if cfg!(target_os = "windows") {
+ "WINDOWS.md"
+ } else if cfg!(target_os = "macos") {
+ "MACOS.md"
+ } else {
+ "LINUX.md"
+ });
+ let path = stage.join(name);
+ if other_platform {
+ assert!(!path.exists(), "{name} belongs to another platform");
+ } else {
+ assert_eq!(std::fs::read_to_string(&path).unwrap(), *text, "{name}");
+ }
+ }
+ // A refresh rewrites only what changed and keeps files it does not own.
+ std::fs::write(stage.join("SKILL.md"), "stale").unwrap();
+ std::fs::write(stage.join("NOTES.md"), "mine").unwrap();
+ stage_embedded(&stage).unwrap();
+ assert_ne!(
+ std::fs::read_to_string(stage.join("SKILL.md")).unwrap(),
+ "stale"
+ );
+ assert_eq!(
+ std::fs::read_to_string(stage.join("NOTES.md")).unwrap(),
+ "mine"
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_linked_stage_is_left_alone() {
+ let root = tempdir().unwrap();
+ let checkout = root.path().join("checkout");
+ std::fs::create_dir_all(&checkout).unwrap();
+ std::fs::write(checkout.join("SKILL.md"), "mine").unwrap();
+ let stage = root.path().join("stage");
+ std::os::unix::fs::symlink(&checkout, &stage).unwrap();
+ stage_embedded(&stage).unwrap();
+ assert_eq!(
+ std::fs::read_to_string(checkout.join("SKILL.md")).unwrap(),
+ "mine"
+ );
+ }
+
+ #[test]
+ fn the_one_line_says_what_happened_and_how_to_undo_it() {
+ let link = PathBuf::from("/home/me/.claude/skills/cua-driver");
+ let created = client_skills_line(
+ "claude",
+ Ok(ClientSkills::Installed(vec![(
+ "Claude Code",
+ link.clone(),
+ true,
+ )])),
+ )
+ .unwrap();
+ assert_eq!(created.lines().count(), 1);
+ assert!(created.contains("installed the skill pack for Claude Code"));
+ assert!(created.contains("/home/me/.claude/skills/cua-driver"));
+ assert!(created.contains("--no-skills"));
+ assert!(created.contains("cua-driver skills uninstall"));
+
+ let again = client_skills_line(
+ "claude",
+ Ok(ClientSkills::Installed(vec![("Claude Code", link, false)])),
+ )
+ .unwrap();
+ assert!(again.contains("already installed"));
+ assert!(!again.contains("--no-skills"));
+
+ let missing =
+ client_skills_line("opencode", Ok(ClientSkills::NotFound(vec!["OpenCode"]))).unwrap();
+ assert!(missing.contains("no OpenCode folder found"));
+ assert!(missing.contains("cua-driver skills install"));
+
+ let failed = client_skills_line("codex", Err(anyhow!("disk full"))).unwrap();
+ assert!(failed.contains("could not install the skill pack for codex: disk full"));
+ assert_eq!(failed.lines().count(), 1);
+
+ assert_eq!(
+ client_skills_line("qwen", Ok(ClientSkills::Unsupported)),
+ None
+ );
+ }
+
#[test]
fn prime_agent_target_matches_its_native_global_skill_directory() {
let target = AGENTS
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/compatibility_contract_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/compatibility_contract_test.rs
index 62941aa1dc..776d135c29 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/compatibility_contract_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/compatibility_contract_test.rs
@@ -85,8 +85,15 @@ fn released_cli_help_and_manifest_fields_remain_compatible() {
#[test]
fn prime_agent_connection_guidance_uses_the_skill_and_cli_path() {
+ // `mcp-config --client` installs the skill pack for that agent by default,
+ // so this run gets a throwaway home instead of the developer's own.
+ let home = tempfile::tempdir().expect("throwaway home");
let output = Command::new(env!("CARGO_BIN_EXE_cua-driver"))
.args(["mcp-config", "--client", "prime-agent"])
+ .env("HOME", home.path())
+ .env("USERPROFILE", home.path())
+ .env("CUA_DRIVER_RS_HOME", home.path().join("driver"))
+ .env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "0")
.output()
.expect("run Prime Agent connection guidance");
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/get_guide_mcp_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/get_guide_mcp_test.rs
new file mode 100644
index 0000000000..56c6a28d00
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/get_guide_mcp_test.rs
@@ -0,0 +1,128 @@
+//! `get_guide` over the real MCP wire: the server instructions and tool
+//! descriptions point at it, and an agent with no skill installed can fetch a
+//! guide, or learn the valid topics from an error, through a tool call.
+
+use cua_driver_testkit::RawDriver;
+use serde_json::{json, Value};
+
+const TOPICS: [&str; 5] = ["drag", "browser", "permissions", "batching", "menus"];
+
+fn spawn() -> Option<RawDriver> {
+ let mut driver = RawDriver::spawn()?;
+ driver.send(&json!({
+ "jsonrpc": "2.0", "id": 1, "method": "initialize",
+ "params": {
+ "protocolVersion": "2024-11-05",
+ "capabilities": {},
+ "clientInfo": { "name": "get-guide-test", "version": "1" }
+ }
+ }));
+ let init = driver.recv();
+ let instructions = init["result"]["instructions"].as_str().unwrap_or_default();
+ assert!(
+ instructions.contains("`get_guide({topic})`"),
+ "the instructions must point at get_guide: {instructions}"
+ );
+ assert!(
+ instructions.split_whitespace().count() <= 200,
+ "the instructions keep their 200-word cap"
+ );
+ for topic in TOPICS {
+ assert!(instructions.contains(topic), "{topic}: {instructions}");
+ }
+ assert!(instructions.contains("skill://cua-driver/SKILL.md"));
+ Some(driver)
+}
+
+fn call(driver: &mut RawDriver, arguments: Value) -> Value {
+ driver.send(&json!({
+ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
+ "params": { "name": "get_guide", "arguments": arguments }
+ }));
+ driver.recv()["result"].clone()
+}
+
+fn text(result: &Value) -> String {
+ result["content"]
+ .as_array()
+ .expect("content array")
+ .iter()
+ .filter_map(|part| part["text"].as_str())
+ .collect::<Vec<_>>()
+ .join("\n")
+}
+
+#[test]
+fn tools_list_has_get_guide_and_the_tools_that_need_it_point_at_it() {
+ let Some(mut driver) = spawn() else { return };
+ driver.send(&json!({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}));
+ let listed = driver.recv();
+ let tools = listed["result"]["tools"].as_array().expect("tools array");
+ let describe = |name: &str| -> Option<String> {
+ tools
+ .iter()
+ .find(|tool| tool["name"] == name)
+ .map(|tool| tool["description"].as_str().unwrap_or_default().to_owned())
+ };
+ let guide = tools
+ .iter()
+ .find(|tool| tool["name"] == "get_guide")
+ .expect("get_guide is listed");
+ assert_eq!(guide["annotations"]["readOnlyHint"], true);
+ for topic in TOPICS {
+ assert!(guide["description"].as_str().unwrap().contains(topic));
+ }
+ for (tool, topic) in [
+ ("drag", "drag"),
+ ("check_permissions", "permissions"),
+ ("get_browser_state", "browser"),
+ ("browser_prepare", "browser"),
+ ("run_steps", "batching"),
+ ("invoke_menu", "menus"),
+ ] {
+ // A tool a platform does not register has nothing to point from.
+ if let Some(description) = describe(tool) {
+ assert!(
+ description.contains(&format!("get_guide({{topic:\"{topic}\"}})")),
+ "{tool}: {description}"
+ );
+ }
+ }
+}
+
+#[test]
+fn an_agent_with_no_skill_installed_can_fetch_the_drag_and_browser_guidance() {
+ let Some(mut driver) = spawn() else { return };
+ for topic in TOPICS {
+ let result = call(&mut driver, json!({ "topic": topic }));
+ assert_ne!(result["isError"].as_bool(), Some(true), "{topic}: {result}");
+ let body = text(&result);
+ assert!(
+ body.starts_with(&format!("Cua Driver guide: {topic}")),
+ "{body}"
+ );
+ assert!(body.len() > 500, "{topic} returned almost nothing");
+ assert_eq!(result["structuredContent"]["topic"], topic);
+ }
+ let drag = text(&call(&mut driver, json!({"topic": "drag"})));
+ assert!(drag.contains("`drag`"), "{drag}");
+ let browser = text(&call(&mut driver, json!({"topic": "browser"})));
+ assert!(browser.contains("browser_prepare"), "{browser}");
+}
+
+#[test]
+fn an_unknown_topic_is_an_error_that_names_the_valid_topics() {
+ let Some(mut driver) = spawn() else { return };
+ let result = call(&mut driver, json!({"topic": "juggling"}));
+ assert_eq!(result["isError"].as_bool(), Some(true), "{result}");
+ let message = text(&result);
+ assert!(message.contains("juggling"), "{message}");
+ for topic in TOPICS {
+ assert!(message.contains(topic), "{message}");
+ }
+ assert_eq!(result["structuredContent"]["code"], "unknown_guide_topic");
+
+ let listed = call(&mut driver, json!({}));
+ assert_ne!(listed["isError"].as_bool(), Some(true));
+ assert!(text(&listed).contains("- menus:"));
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/mcp_config_skills_cli_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/mcp_config_skills_cli_test.rs
new file mode 100644
index 0000000000..319a392ac8
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/mcp_config_skills_cli_test.rs
@@ -0,0 +1,337 @@
+//! `cua-driver mcp-config --client <agent>` installs the skill pack for that
+//! agent by default, prints one line about it on stderr, and leaves the agent
+//! alone with `--no-skills`. Every run uses a throwaway home.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Output, Stdio};
+
+use tempfile::TempDir;
+
+const SKILL: &str = include_str!("../../../Skills/cua-driver/SKILL.md");
+
+struct Sandbox {
+ _root: TempDir,
+ home: PathBuf,
+ driver_home: PathBuf,
+ hermes_home: PathBuf,
+}
+
+impl Sandbox {
+ fn new() -> Self {
+ let root = tempfile::tempdir().expect("temporary test root");
+ let home = root.path().join("home");
+ fs::create_dir_all(&home).unwrap();
+ Sandbox {
+ driver_home: root.path().join("driver"),
+ hermes_home: home.join(".hermes"),
+ home,
+ _root: root,
+ }
+ }
+
+ /// An agent that has been started once: its own folder exists.
+ fn has(&self, relative: &str) {
+ fs::create_dir_all(self.home.join(relative)).unwrap();
+ }
+
+ fn run(&self, args: &[&str]) -> Output {
+ Command::new(env!("CARGO_BIN_EXE_cua-driver"))
+ .arg("mcp-config")
+ .args(args)
+ .stdin(Stdio::null())
+ .env("HOME", &self.home)
+ .env("USERPROFILE", &self.home)
+ .env("APPDATA", self.home.join("AppData/Roaming"))
+ .env("CUA_DRIVER_RS_HOME", &self.driver_home)
+ .env("HERMES_HOME", &self.hermes_home)
+ .env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "0")
+ .output()
+ .expect("run cua-driver mcp-config")
+ }
+
+ fn stage(&self) -> PathBuf {
+ self.driver_home.join("skills").join("cua-driver")
+ }
+}
+
+fn stderr(output: &Output) -> String {
+ String::from_utf8_lossy(&output.stderr).into_owned()
+}
+
+fn stdout(output: &Output) -> String {
+ String::from_utf8_lossy(&output.stdout).into_owned()
+}
+
+fn only_line(output: &Output) -> String {
+ let text = stderr(output);
+ let lines: Vec<&str> = text
+ .lines()
+ .filter(|line| !line.trim().is_empty())
+ .collect();
+ assert_eq!(lines.len(), 1, "expected one line on stderr: {text:?}");
+ lines[0].to_owned()
+}
+
+fn assert_nothing_installed(sandbox: &Sandbox) {
+ assert!(
+ !sandbox.driver_home.exists(),
+ "no local skill pack expected"
+ );
+ for relative in [
+ ".claude/skills",
+ ".agents/skills",
+ ".config/opencode/skills",
+ ] {
+ assert!(
+ !sandbox.home.join(relative).exists(),
+ "{relative} should not exist"
+ );
+ }
+}
+
+#[test]
+fn no_skills_leaves_the_agent_alone_and_keeps_stdout_the_same() {
+ let with = Sandbox::new();
+ with.has(".claude");
+ let installed = with.run(&["--client", "claude"]);
+
+ let without = Sandbox::new();
+ without.has(".claude");
+ let skipped = without.run(&["--client", "claude", "--no-skills"]);
+
+ assert!(installed.status.success() && skipped.status.success());
+ assert_eq!(stdout(&installed), stdout(&skipped));
+ assert!(stdout(&skipped).starts_with("claude mcp add-json"));
+ assert!(stderr(&skipped).is_empty(), "{}", stderr(&skipped));
+ assert_nothing_installed(&without);
+ assert!(!without.home.join(".claude/skills").exists());
+ // The flag works in either position.
+ let first = without.run(&["--no-skills", "--client", "claude"]);
+ assert!(first.status.success() && stderr(&first).is_empty());
+ assert_nothing_installed(&without);
+}
+
+#[test]
+fn the_generic_snippet_and_unsupported_clients_install_nothing() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".claude");
+ sandbox.has(".codex");
+ for args in [
+ &[][..],
+ &["--client", "qwen"],
+ &["--client", "droid"],
+ &["--client", "zcode"],
+ ] {
+ let output = sandbox.run(args);
+ assert!(output.status.success(), "{args:?}: {output:?}");
+ assert!(stderr(&output).is_empty(), "{args:?}: {}", stderr(&output));
+ }
+ assert_nothing_installed(&sandbox);
+}
+
+#[test]
+fn an_unknown_client_is_refused_before_anything_is_installed() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".claude");
+ let output = sandbox.run(&["--client", "emacs"]);
+ assert_eq!(output.status.code(), Some(2));
+ assert!(stderr(&output).contains("Unknown client 'emacs'"));
+ assert_nothing_installed(&sandbox);
+}
+
+#[test]
+fn an_agent_that_is_not_on_this_computer_gets_a_hint_not_a_folder() {
+ let sandbox = Sandbox::new();
+ let output = sandbox.run(&["--client", "claude"]);
+ assert!(output.status.success());
+ assert!(stdout(&output).starts_with("claude mcp add-json"));
+ let line = only_line(&output);
+ assert!(line.contains("no Claude Code folder found"), "{line}");
+ assert!(line.contains("cua-driver skills install"), "{line}");
+ assert_nothing_installed(&sandbox);
+}
+
+#[cfg(unix)]
+mod placement {
+ use super::*;
+ use std::os::unix::fs::symlink;
+
+ /// Where each supported agent loads skills from: the agent's own folder
+ /// (made first, as the agent does on its first run) and the link the
+ /// skill pack must land at.
+ const AGENTS: &[(&str, &str, &[&str])] = &[
+ ("claude", ".claude", &[".claude/skills/cua-driver"]),
+ ("claude-code", ".claude", &[".claude/skills/cua-driver"]),
+ ("codex", ".codex", &[".agents/skills/cua-driver"]),
+ ("cursor", ".cursor", &[".agents/skills/cua-driver"]),
+ ("pi", ".pi/agent", &[".agents/skills/cua-driver"]),
+ ("openclaw", ".openclaw", &[".openclaw/skills/cua-driver"]),
+ (
+ "opencode",
+ ".config/opencode",
+ &[".config/opencode/skills/cua-driver"],
+ ),
+ ("hermes", ".hermes", &[".hermes/skills/cua-driver"]),
+ (
+ "prime-agent",
+ ".prime/agent",
+ &[".prime/agent/skills/cua-driver"],
+ ),
+ (
+ "antigravity",
+ ".gemini/config",
+ &[".gemini/config/skills/cua-driver"],
+ ),
+ (
+ "gemini",
+ ".gemini/antigravity-cli",
+ &[".gemini/antigravity-cli/skills/cua-driver"],
+ ),
+ ];
+
+ fn assert_linked_to_the_pack(sandbox: &Sandbox, link: &Path) {
+ let meta = fs::symlink_metadata(link).unwrap_or_else(|_| panic!("{link:?} missing"));
+ assert!(meta.file_type().is_symlink(), "{link:?} should be a link");
+ assert_eq!(fs::read_link(link).unwrap(), sandbox.stage());
+ assert_eq!(
+ fs::read_to_string(link.join("SKILL.md")).unwrap(),
+ SKILL,
+ "the agent reads the SKILL.md compiled into this driver"
+ );
+ }
+
+ #[test]
+ fn each_supported_agent_gets_the_skill_pack_where_it_loads_skills() {
+ for (client, folder, links) in AGENTS {
+ let sandbox = Sandbox::new();
+ sandbox.has(folder);
+ let output = sandbox.run(&["--client", client]);
+ assert!(output.status.success(), "{client}: {output:?}");
+ for link in *links {
+ assert_linked_to_the_pack(&sandbox, &sandbox.home.join(link));
+ }
+ let line = only_line(&output);
+ assert!(
+ line.contains("installed the skill pack"),
+ "{client}: {line}"
+ );
+ assert!(line.contains("--no-skills"), "{client}: {line}");
+ assert!(
+ line.contains(&sandbox.home.join(links[0]).display().to_string()),
+ "{client}: {line}"
+ );
+ // The config on stdout is the same with or without the install.
+ let skipped = sandbox.run(&["--client", client, "--no-skills"]);
+ assert_eq!(stdout(&output), stdout(&skipped), "{client}");
+ assert!(
+ stderr(&skipped).is_empty(),
+ "{client}: {}",
+ stderr(&skipped)
+ );
+ }
+ }
+
+ #[test]
+ fn antigravity_gets_both_the_ide_and_the_cli_folder_that_exist() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".gemini/config");
+ sandbox.has(".gemini/antigravity-cli");
+ let output = sandbox.run(&["--client", "antigravity"]);
+ assert!(output.status.success());
+ assert_linked_to_the_pack(
+ &sandbox,
+ &sandbox.home.join(".gemini/config/skills/cua-driver"),
+ );
+ assert_linked_to_the_pack(
+ &sandbox,
+ &sandbox
+ .home
+ .join(".gemini/antigravity-cli/skills/cua-driver"),
+ );
+ assert_eq!(only_line(&output).matches("skill pack").count(), 1);
+ }
+
+ #[test]
+ fn the_pack_is_this_drivers_own_and_only_for_this_host() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".claude");
+ sandbox.run(&["--client", "claude"]);
+ let stage = sandbox.stage();
+ for file in ["SKILL.md", "WORKFLOW.md", "BROWSER.md", "RUNTIME.md"] {
+ assert!(stage.join(file).is_file(), "{file} missing from the pack");
+ }
+ let (own, others) = if cfg!(target_os = "macos") {
+ ("MACOS.md", ["WINDOWS.md", "LINUX.md"])
+ } else {
+ ("LINUX.md", ["WINDOWS.md", "MACOS.md"])
+ };
+ assert!(stage.join(own).is_file());
+ for other in others {
+ assert!(!stage.join(other).exists(), "{other} is another platform's");
+ }
+ }
+
+ #[test]
+ fn rerunning_is_idempotent_and_refreshes_a_stale_pack() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".codex");
+ let first = sandbox.run(&["--client", "codex"]);
+ assert!(only_line(&first).contains("installed the skill pack"));
+ fs::write(sandbox.stage().join("SKILL.md"), "stale").unwrap();
+
+ let second = sandbox.run(&["--client", "codex"]);
+ assert!(second.status.success());
+ assert!(
+ only_line(&second).contains("already installed"),
+ "{}",
+ stderr(&second)
+ );
+ assert_linked_to_the_pack(&sandbox, &sandbox.home.join(".agents/skills/cua-driver"));
+ }
+
+ #[test]
+ fn a_skill_folder_the_user_made_is_never_replaced() {
+ let sandbox = Sandbox::new();
+ let mine = sandbox.home.join(".claude/skills/cua-driver");
+ fs::create_dir_all(&mine).unwrap();
+ fs::write(mine.join("SKILL.md"), "my own notes").unwrap();
+
+ let output = sandbox.run(&["--client", "claude"]);
+ assert!(output.status.success());
+ assert!(only_line(&output).contains("already installed"));
+ assert_eq!(
+ fs::read_to_string(mine.join("SKILL.md")).unwrap(),
+ "my own notes"
+ );
+ assert!(!fs::symlink_metadata(&mine)
+ .unwrap()
+ .file_type()
+ .is_symlink());
+ }
+
+ #[test]
+ fn a_developers_linked_pack_is_linked_to_not_overwritten() {
+ let sandbox = Sandbox::new();
+ sandbox.has(".claude");
+ let checkout = sandbox.home.join("checkout/Skills/cua-driver");
+ fs::create_dir_all(&checkout).unwrap();
+ fs::write(checkout.join("SKILL.md"), "work in progress").unwrap();
+ fs::create_dir_all(sandbox.driver_home.join("skills")).unwrap();
+ symlink(&checkout, sandbox.stage()).unwrap();
+
+ let output = sandbox.run(&["--client", "claude"]);
+ assert!(output.status.success());
+ assert_eq!(
+ fs::read_to_string(checkout.join("SKILL.md")).unwrap(),
+ "work in progress",
+ "the checkout behind the link must not be rewritten"
+ );
+ assert!(
+ fs::symlink_metadata(sandbox.home.join(".claude/skills/cua-driver"))
+ .unwrap()
+ .file_type()
+ .is_symlink()
+ );
+ }
+}
diff --git a/libs/cua/crates/cua-agent-setup/tests/driver_skills.rs b/libs/cua/crates/cua-agent-setup/tests/driver_skills.rs
new file mode 100644
index 0000000000..6298abf30a
--- /dev/null
+++ b/libs/cua/crates/cua-agent-setup/tests/driver_skills.rs
@@ -0,0 +1,163 @@
+//! Setting up cua-driver for an agent installs the cua-driver skill by
+//! default, in the folder that agent loads skills from, and `skills: false`
+//! (the engine behind `cua agents setup --cua-driver --no-skills` and the
+//! installers' `--no-skills`) leaves every skills folder untouched. Always in
+//! a temporary HOME, never the real one.
+
+use cua_agent_setup::{AGENTS, AgentSetup, Change, HostEnv, McpServer, Parts, Target};
+use std::path::{Path, PathBuf};
+
+struct Home {
+ _dir: tempfile::TempDir,
+ path: PathBuf,
+ env: HostEnv,
+}
+
+impl Home {
+ fn new() -> Self {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("home");
+ std::fs::create_dir_all(&path).unwrap();
+ let env = HostEnv::isolated(&path);
+ Home {
+ _dir: dir,
+ path,
+ env,
+ }
+ }
+
+ fn setup(&self) -> AgentSetup {
+ AgentSetup::new(self.env.clone())
+ }
+}
+
+fn driver() -> McpServer {
+ McpServer::driver("/opt/drv/bin/cua-driver")
+}
+
+fn ids(id: &str) -> Vec<String> {
+ vec![id.to_string()]
+}
+
+/// Every file under `dir`, for "nothing was written here".
+fn files_under(dir: &Path) -> Vec<PathBuf> {
+ let mut out = Vec::new();
+ let Ok(entries) = std::fs::read_dir(dir) else {
+ return out;
+ };
+ for entry in entries.flatten() {
+ let path = entry.path();
+ if path.is_dir() {
+ out.extend(files_under(&path));
+ } else {
+ out.push(path);
+ }
+ }
+ out
+}
+
+#[test]
+fn every_agent_with_a_skills_folder_gets_the_driver_skill_by_default() {
+ let with_skills: Vec<_> = AGENTS.iter().filter(|a| a.skills.is_some()).collect();
+ assert!(with_skills.len() >= 15, "registry lost agents");
+ for agent in with_skills {
+ let home = Home::new();
+ let skills_dir = agent.skills.unwrap().resolve(&home.env);
+ let out = home
+ .setup()
+ .setup_cua_driver(&ids(agent.id), &driver(), Parts::ALL, false)
+ .unwrap();
+
+ let skill: Vec<_> = out
+ .iter()
+ .filter(|o| o.target == Target::Skill && o.item == "cua-driver")
+ .collect();
+ assert_eq!(skill.len(), 1, "{}: {out:#?}", agent.id);
+ assert_eq!(skill[0].change, Change::Created, "{}: {out:#?}", agent.id);
+ assert_eq!(skill[0].path, skills_dir.join("cua-driver"), "{}", agent.id);
+ let md =
+ std::fs::read_to_string(skills_dir.join("cua-driver/SKILL.md")).unwrap_or_else(|e| {
+ panic!("{}: no SKILL.md in {}: {e}", agent.id, skills_dir.display())
+ });
+ assert!(md.contains("\nname: cua-driver\n"), "{}", agent.id);
+ // Only the driver skill: the other bundled skills are not forced on
+ // someone who asked for background computer-use.
+ assert!(!skills_dir.join("cua-spaces").exists(), "{}", agent.id);
+ }
+}
+
+#[test]
+fn no_skills_leaves_every_skills_folder_untouched() {
+ for agent in AGENTS.iter().filter(|a| a.skills.is_some()) {
+ let home = Home::new();
+ let skills_dir = agent.skills.unwrap().resolve(&home.env);
+ let out = home
+ .setup()
+ .setup_cua_driver(
+ &ids(agent.id),
+ &driver(),
+ Parts {
+ skills: false,
+ mcp: true,
+ },
+ false,
+ )
+ .unwrap();
+ assert!(
+ out.iter().all(|o| o.target == Target::Mcp),
+ "{}: {out:#?}",
+ agent.id
+ );
+ assert!(
+ !skills_dir.join("cua-driver").exists(),
+ "{}: --no-skills must not install the skill",
+ agent.id
+ );
+ assert!(
+ files_under(&skills_dir).is_empty(),
+ "{}: {:?}",
+ agent.id,
+ files_under(&skills_dir)
+ );
+ }
+}
+
+#[test]
+fn skills_only_installs_the_skill_without_touching_mcp_config() {
+ let home = Home::new();
+ let out = home
+ .setup()
+ .setup_cua_driver(
+ &ids("claude-code"),
+ &driver(),
+ Parts {
+ skills: true,
+ mcp: false,
+ },
+ false,
+ )
+ .unwrap();
+ assert!(out.iter().all(|o| o.target == Target::Skill), "{out:#?}");
+ assert!(
+ home.path
+ .join(".claude/skills/cua-driver/SKILL.md")
+ .is_file()
+ );
+ assert!(!home.path.join(".claude.json").exists());
+}
+
+#[test]
+fn rerunning_the_setup_changes_nothing() {
+ let home = Home::new();
+ let setup = home.setup();
+ setup
+ .setup_cua_driver(&ids("codex"), &driver(), Parts::ALL, false)
+ .unwrap();
+ let again = setup
+ .setup_cua_driver(&ids("codex"), &driver(), Parts::ALL, false)
+ .unwrap();
+ assert!(
+ again.iter().all(|o| o.change == Change::Unchanged),
+ "{again:#?}"
+ );
+}
diff --git a/libs/cua/crates/cua-cli/tests/agents_login.rs b/libs/cua/crates/cua-cli/tests/agents_login.rs
index 3401dbc328..54a6b39881 100644
--- a/libs/cua/crates/cua-cli/tests/agents_login.rs
+++ b/libs/cua/crates/cua-cli/tests/agents_login.rs
@@ -501,6 +501,61 @@ async fn agents_setup_cua_driver_adds_the_driver_skill_and_server() {
assert!(!h.dir.path().join(".claude/skills/cua-driver").exists());
}
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn agents_setup_cua_driver_says_where_the_skill_went_and_no_skills_skips_it() {
+ let h = home();
+ mkdirs(&h, &[".codex", ".claude"]);
+ let skill = |rel: &str| h.dir.path().join(rel).join("cua-driver/SKILL.md");
+
+ // Default: the skill lands beside the MCP entry, with one line saying so.
+ let o = h
+ .run(&[
+ "agents",
+ "setup",
+ "--cua-driver",
+ "--agents",
+ "claude",
+ "--yes",
+ "--mcp-command",
+ "/opt/drv/cua-driver",
+ ])
+ .await;
+ o.ok();
+ let said: Vec<&str> = o
+ .stdout
+ .lines()
+ .filter(|l| l.contains("skill cua-driver"))
+ .collect();
+ assert_eq!(said.len(), 1, "{o:?}");
+ assert!(said[0].contains(".claude/skills/cua-driver"), "{o:?}");
+ assert!(skill(".claude/skills").is_file());
+
+ // --no-skills (the installers' flag): the server only, nothing printed
+ // about a skill, and Codex's skills folder is never created.
+ let o = h
+ .run(&[
+ "agents",
+ "setup",
+ "--cua-driver",
+ "--agents",
+ "codex",
+ "--no-skills",
+ "--yes",
+ "--mcp-command",
+ "/opt/drv/cua-driver",
+ ])
+ .await;
+ o.ok();
+ assert!(
+ o.stdout
+ .contains("MCP server cua-driver: ~/.codex/config.toml added"),
+ "{o:?}"
+ );
+ assert!(!o.stdout.contains("skill cua-driver"), "{o:?}");
+ assert!(!skill(".agents/skills").exists());
+ assert!(!h.dir.path().join(".agents/skills").exists());
+}
+
// ------------------------------------------------------------ PTY (expect)
/// A `cua` process on a pseudo-terminal, driven like `expect`.
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
index 037e67246e..73074144f0 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
@@ -437,7 +437,7 @@
"read_only": false
},
{
- "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels.",
+ "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:\"menus\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -746,7 +746,7 @@
"read_only": false
},
{
- "description": "Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release) — it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal.",
+ "description": "Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release) — it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal. Limits and fallbacks: `get_guide({topic:\"drag\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2053,7 +2053,7 @@
"read_only": false
},
{
- "description": "Check required permissions for cua-driver-rs on Linux.",
+ "description": "Check required permissions for cua-driver-rs on Linux. How to get them granted: `get_guide({topic:\"permissions\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2393,7 +2393,7 @@
"read_only": false
},
{
- "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.",
+ "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2451,7 +2451,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3359,7 +3359,28 @@
"read_only": false
},
{
- "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}}",
+ "description": "Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.",
+ "destructive": false,
+ "idempotent": true,
+ "input_schema": {
+ "additionalProperties": false,
+ "properties": {
+ "session": {
+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",
+ "type": "string"
+ },
+ "topic": {
+ "description": "One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "name": "get_guide",
+ "read_only": true
+ },
+ {
+ "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}} Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3467,7 +3488,7 @@
"read_only": false
},
{
- "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",
+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value; Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
index 749eca7554..5d071c22ba 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -442,7 +442,7 @@
"read_only": false
},
{
- "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels.",
+ "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:\"menus\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -710,7 +710,7 @@
"read_only": false
},
{
- "description": "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.\n\nUse for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbing a slider, repositioning a panel.\n\n`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.\n\n`modifier` keys (cmd/shift/option/ctrl) are held across the entire gesture.\n\nWhen `from_zoom` is true, coordinates are in the last zoom image for this pid; the driver maps them back to window coordinates before dispatching.\n\nA window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:\"drag\" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:\"foreground\", which briefly fronts the window and moves the physical pointer.",
+ "description": "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.\n\nUse for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbing a slider, repositioning a panel.\n\n`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.\n\n`modifier` keys (cmd/shift/option/ctrl) are held across the entire gesture.\n\nWhen `from_zoom` is true, coordinates are in the last zoom image for this pid; the driver maps them back to window coordinates before dispatching.\n\nA window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:\"drag\" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:\"foreground\", which briefly fronts the window and moves the physical pointer. Limits and fallbacks: `get_guide({topic:\"drag\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -1699,7 +1699,7 @@
"read_only": true
},
{
- "description": "Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants — Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass {\"prompt\": false} for a purely read-only status check.\n\nReturns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent.",
+ "description": "Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants — Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass {\"prompt\": false} for a purely read-only status check.\n\nReturns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent. How to get them granted: `get_guide({topic:\"permissions\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2036,7 +2036,7 @@
"read_only": false
},
{
- "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.",
+ "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2094,7 +2094,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3002,7 +3002,28 @@
"read_only": false
},
{
- "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}}",
+ "description": "Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.",
+ "destructive": false,
+ "idempotent": true,
+ "input_schema": {
+ "additionalProperties": false,
+ "properties": {
+ "session": {
+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",
+ "type": "string"
+ },
+ "topic": {
+ "description": "One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "name": "get_guide",
+ "read_only": true
+ },
+ {
+ "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}} Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3110,7 +3131,7 @@
"read_only": false
},
{
- "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",
+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value; Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
index b7660e12a2..744913c198 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -458,7 +458,7 @@
"read_only": false
},
{
- "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels.",
+ "description": "Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:\"menus\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -764,7 +764,7 @@
"read_only": false
},
{
- "description": "Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background — the OS move/resize loop needs real pointer input — so they return background_unavailable; re-issue those with delivery_mode:\"foreground\".",
+ "description": "Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background — the OS move/resize loop needs real pointer input — so they return background_unavailable; re-issue those with delivery_mode:\"foreground\". Limits and fallbacks: `get_guide({topic:\"drag\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -1748,7 +1748,7 @@
"read_only": false
},
{
- "description": "Check required permissions for cua-driver-rs on Windows.",
+ "description": "Check required permissions for cua-driver-rs on Windows. How to get them granted: `get_guide({topic:\"permissions\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2088,7 +2088,7 @@
"read_only": false
},
{
- "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.",
+ "description": "Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": false,
"idempotent": true,
"input_schema": {
@@ -2146,7 +2146,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:\"browser\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3054,7 +3054,28 @@
"read_only": false
},
{
- "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}}",
+ "description": "Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.",
+ "destructive": false,
+ "idempotent": true,
+ "input_schema": {
+ "additionalProperties": false,
+ "properties": {
+ "session": {
+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",
+ "type": "string"
+ },
+ "topic": {
+ "description": "One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "name": "get_guide",
+ "read_only": true
+ },
+ {
+ "description": "The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.\n\nReturns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:\"latest\"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.\n\nTARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{\"click\": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.\n\nWAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is {role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?}: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.\n\nExample (fill a form, submit, confirm the dialog, check the result):\n{\"steps\":[{\"set_value\":{\"app\":\"Safari\",\"role\":\"textfield\",\"name\":\"Email\",\"value\":\"[email protected]\"}},{\"click\":{\"role\":\"button\",\"name\":\"Submit\"},\"expect\":[{\"role\":\"button\",\"name\":\"Confirm\"}]},{\"click\":{\"role\":\"button\",\"name\":\"Confirm\"},\"expect\":[{\"name\":\"Confirm\",\"gone\":true},{\"text\":\"Thanks\"}]}],\"observe\":{}} Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -3162,7 +3183,7 @@
"read_only": false
},
{
- "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",
+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value; Batching rules: `get_guide({topic:\"batching\"})`.",
"destructive": true,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.json
index 37e030185d..f7aaeb71ca 100644
--- a/scripts/docs-generators/cli-specs/cua-driver.json
+++ b/scripts/docs-generators/cli-specs/cua-driver.json
@@ -783,9 +783,9 @@
]
},
{
- "abstract": "Print client-specific connection guidance (MCP config where supported).",
+ "abstract": "Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.",
"arguments": [],
- "discussion": "Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode.",
+ "discussion": "Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.",
"examples": [
{
"command": "cua-driver mcp-config",
@@ -793,10 +793,21 @@
},
{
"command": "cua-driver mcp-config --client codex",
- "description": "Print setup for Codex"
+ "description": "Print setup for Codex and install its skill pack"
+ },
+ {
+ "command": "cua-driver mcp-config --client codex --no-skills",
+ "description": "Print setup for Codex only"
+ }
+ ],
+ "flags": [
+ {
+ "default_value": false,
+ "help": "With --client, do not install the cua-driver skill pack for that agent.",
+ "name": "no-skills",
+ "short_name": null
}
],
- "flags": [],
"name": "mcp-config",
"options": [
{
diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.ts
index 3e4f8e629a..afa29f41d6 100644
--- a/scripts/docs-generators/cua-driver.ts
+++ b/scripts/docs-generators/cua-driver.ts
@@ -348,8 +348,8 @@ export const MCP_CATEGORIES: Array<McpCategory & { tools: string[] }> = [
{
slug: 'maintenance',
title: 'Configuration and maintenance tools',
- summary: 'Configuration, permissions, health, updates and extensions',
- tools: ['get_config', 'set_config', 'check_permissions', 'health_report', 'check_for_update', 'install_extension'],
+ summary: 'Configuration, permissions, health, updates, extensions and on-demand guides',
+ tools: ['get_config', 'set_config', 'check_permissions', 'health_report', 'check_for_update', 'install_extension', 'get_guide'],
},
];
diff --git a/scripts/install/install.ps1 b/scripts/install/install.ps1
index e31cad9916..7a643de202 100644
--- a/scripts/install/install.ps1
+++ b/scripts/install/install.ps1
@@ -60,6 +60,8 @@ Kept for older commands: the CLI directory is added to the user PATH by default.
Do not add the CLI directory to the user PATH.
.PARAMETER NoOnboarding
Do not run `cua auth login` afterwards.
+.PARAMETER NoSkills
+With cua-driver, add only its MCP server to your agents, not its skill (by default both are added).
.PARAMETER RequireSignature
Fail unless a signature verifies.
.PARAMETER Installer
@@ -83,6 +85,7 @@ param(
[switch]$ModifyPath,
[switch]$NoModifyPath,
[switch]$NoOnboarding,
+ [switch]$NoSkills,
[switch]$RequireSignature,
[ValidateSet('msi', 'nsis')][string]$Installer = 'nsis',
[switch]$DryRun,
@@ -490,8 +493,10 @@ function Install-CuaDriver([string]$Cua, [string]$Tmp, [string]$ManifestUrl) {
try { & $exe -NoProfile -ExecutionPolicy Bypass -File $script @driverArgs } finally { $env:CUA_DRIVER_RS_INSTALL_DIR = $saved }
if ($LASTEXITCODE -ne 0) { Stop-Install "the cua-driver installer failed (exit $LASTEXITCODE)" }
}
- Write-Info 'adding the cua-driver skill and MCP server to your agents'
+ if ($NoSkills) { Write-Info 'adding the cua-driver MCP server to your agents (no skill: -NoSkills)' }
+ else { Write-Info 'adding the cua-driver skill and MCP server to your agents' }
$setup = @('agents', 'setup', '--cua-driver', '--agents', 'all', '--yes')
+ if ($NoSkills) { $setup += '--no-skills' }
$driver = Join-Path $binDir 'cua-driver.exe'
if ($DryRun -or (Test-Path -LiteralPath $driver)) { $setup += @('--mcp-command', $driver) }
if ($DryRun) { Write-Host "[dry-run] $Cua $($setup -join ' ')"; return }
diff --git a/scripts/install/install.sh b/scripts/install/install.sh
index 9003505fd3..4bda6cdada 100755
--- a/scripts/install/install.sh
+++ b/scripts/install/install.sh
@@ -36,6 +36,8 @@
# --modify-path add the bin dir to your shell profile without asking
# --no-modify-path never edit your shell profile (print the one-line command)
# --no-onboarding do not run `cua auth login` afterwards
+# --no-skills with cua-driver, add only its MCP server to your agents,
+# not its skill (by default both are added)
# -v, --verbose print every step (manifest, downloads, signature checks)
# --require-signature fail unless a signature (minisign/cosign) verifies
# --dry-run print what would happen, change nothing
@@ -90,6 +92,7 @@ verbose=0
no_tty_noted=0
signed_in=0
onboarding=1
+driver_skills=1
require_sig=0
dry_run=0
assume_yes=0
@@ -189,6 +192,7 @@ parse_args() {
--modify-path) modify_path=1 ;;
--no-modify-path) no_modify_path=1 ;;
--no-onboarding) onboarding=0 ;;
+ --no-skills) driver_skills=0 ;;
-v | --verbose) verbose=1 ;;
--require-signature) require_sig=1 ;;
--dry-run) dry_run=1 ;;
@@ -1017,8 +1021,13 @@ install_driver() {
fetch "$driver_url" "$script"
bash "$script" "$@" </dev/null || die "the cua-driver installer failed"
fi
- info "adding the cua-driver skill and MCP server to your agents"
+ if [ "$driver_skills" = 1 ]; then
+ info "adding the cua-driver skill and MCP server to your agents"
+ else
+ info "adding the cua-driver MCP server to your agents (no skill: --no-skills)"
+ fi
set -- "$cua_bin" agents setup --cua-driver --agents all --yes
+ [ "$driver_skills" = 1 ] || set -- "$@" --no-skills
if [ "$dry_run" = 1 ] || [ -x "$driver_dir/cua-driver" ]; then
set -- "$@" --mcp-command "$driver_dir/cua-driver"
fi
diff --git a/scripts/install/tests/install.Tests.ps1 b/scripts/install/tests/install.Tests.ps1
index 382b6f8481..0cb93fc47e 100644
--- a/scripts/install/tests/install.Tests.ps1
+++ b/scripts/install/tests/install.Tests.ps1
@@ -182,6 +182,28 @@ Set-Content (Join-Path `$env:CUA_DRIVER_RS_INSTALL_DIR 'cua-driver.exe') 'fake'
$env:CUA_DRIVER_RS_INSTALL_DIR | Should -BeNullOrEmpty
}
+ It 'adds the MCP server without the skill with -NoSkills' -Skip:($IsWindows) {
+ $root = Join-Path $env:CUA_TEST_ROOT 'noskills'
+ $prefix = Join-Path $root 'prefix'
+ New-Item -ItemType Directory -Force -Path $root | Out-Null
+ $cuaLog = Join-Path $root 'cua.log'
+ $fakeDriver = Join-Path $root 'install.ps1'
+ Set-Content -LiteralPath $fakeDriver -Value @"
+param([switch]`$NoPathUpdate, [switch]`$RequireSignature)
+New-Item -ItemType Directory -Force -Path `$env:CUA_DRIVER_RS_INSTALL_DIR | Out-Null
+Set-Content (Join-Path `$env:CUA_DRIVER_RS_INSTALL_DIR 'cua-driver.exe') 'fake'
+"@
+ $fakeCua = Join-Path $root 'cua'
+ Set-Content -LiteralPath $fakeCua -Value "#!/bin/sh`necho `"`$*`" >>'$cuaLog'"
+ chmod +x $fakeCua
+ $env:CUA_INSTALL_DRIVER_URL = ConvertTo-FileUrl $fakeDriver
+ $Prefix = $prefix; $DryRun = $false; $NoModifyPath = $true; $NoSkills = $true
+ try {
+ Install-CuaDriver $fakeCua (New-Item -ItemType Directory -Force -Path (Join-Path $root 'tmp')).FullName 'file:///r.json' 6>$null
+ } finally { $env:CUA_INSTALL_DRIVER_URL = $null; $NoSkills = $false }
+ Get-Content $cuaLog | Should -Be "agents setup --cua-driver --agents all --yes --no-skills --mcp-command $(Join-Path (Join-Path $prefix 'bin') 'cua-driver.exe')"
+ }
+
It 'refuses a plain-HTTP cua-driver installer URL' {
$env:CUA_INSTALL_DRIVER_URL = 'http://example.invalid/install.ps1'
$DryRun = $false
@@ -373,6 +395,11 @@ Describe 'install.ps1' {
$out | Should -Not -Match 'msiexec'
}
+ It 'dry run: -NoSkills leaves the skill out of the planned agent setup' {
+ $out = Invoke-Installer @{ DryRun = $true; Select = 'cua-driver'; NoSkills = $true; Prefix = (Join-Path $env:CUA_TEST_ROOT 'p11') } @{ CUA_INSTALL_NONINTERACTIVE = '1'; CUA_INSTALL_DRIVER_URL = 'https://example.test/driver/install.ps1' }
+ $out | Should -Match 'agents setup --cua-driver --agents all --yes --no-skills --mcp-command .*p11.bin.cua-driver.exe'
+ }
+
It 'dry run: -Select cua-driver,host prints the driver, agents and host steps' {
$out = Invoke-Installer @{ DryRun = $true; Select = 'cua-driver,host'; Prefix = (Join-Path $env:CUA_TEST_ROOT 'p10') } @{ CUA_INSTALL_NONINTERACTIVE = '1'; CUA_INSTALL_DRIVER_URL = 'https://example.test/driver/install.ps1' }
$out | Should -Match '\[dry-run\] download https://example.test/driver/install.ps1'
diff --git a/scripts/install/tests/run.sh b/scripts/install/tests/run.sh
index cb339f3093..4062230fdf 100755
--- a/scripts/install/tests/run.sh
+++ b/scripts/install/tests/run.sh
@@ -248,6 +248,10 @@ if command -v bash >/dev/null 2>&1; then
check "--select cua-driver: the driver lands in --prefix/bin" exists "$work/d1/bin/cua-driver"
check "--select cua-driver: registers the skill and MCP server" sh -c "grep -qx -- 'agents setup --cua-driver --agents all --yes --mcp-command $work/d1/bin/cua-driver' '$home/cua.log'"
check "--select cua-driver: no host setup" sh -c "! grep -q 'host setup' '$home/cua.log'"
+ check "--select cua-driver: adds the skill by default (no --no-skills)" sh -c "! grep -q -- '--no-skills' '$home/cua.log'"
+
+ inst CUA_INSTALL_DRIVER_URL="$driver_url" -- --no-onboarding --select cua-driver --no-skills --prefix "$work/d1s"
+ check "--no-skills: still registers the MCP server, without the skill" sh -c "[ $status = 0 ] && grep -qx -- 'agents setup --cua-driver --agents all --yes --no-skills --mcp-command $work/d1s/bin/cua-driver' '$home/cua.log'"
if [ "$(id -u)" != 0 ]; then
inst CUA_INSTALL_DRIVER_URL="$driver_url" -- --yes --no-onboarding --modify-path --select cua-driver
@@ -291,6 +295,8 @@ check "--pair: no sign-in next steps" sh -c "! grep -q 'cua auth login' '$work/o
inst CUA_INSTALL_DRIVER_URL="$driver_url" -- --dry-run --select cua-driver,host --prefix "$work/dr"
check "--dry-run prints the driver, agents and host steps" sh -c "grep -q 'dry-run. download $driver_url' '$work/out' && grep -q 'dry-run. bash cua-driver-install.sh --bin-dir' '$work/out' && grep -q 'dry-run. .* agents setup --cua-driver --agents all --yes' '$work/out' && grep -q 'dry-run. .* host setup' '$work/out'"
+inst CUA_INSTALL_DRIVER_URL="$driver_url" -- --dry-run --select cua-driver --no-skills --prefix "$work/drs"
+check "--dry-run --no-skills: the planned agent setup leaves the skill out" sh -c "grep -q 'dry-run. .* agents setup --cua-driver --agents all --yes --no-skills' '$work/out'"
check "--dry-run runs nothing" sh -c "[ ! -e '$home/cua.log' ] && [ ! -e '$home/driver.log' ] && [ ! -e '$work/dr' ]"
inst -- --yes --select bogus