docs(cua-driver): audit fixes across macOS/Linux/Windows - #2089
Merged
Conversation
…ssions status Iteration 1 live-audit fixes (verified against cua-driver 0.7.0): - tutorial: result was reported as 391, contradicting its own step 4 (42) - install: --version/doctor showed 0.5.x; live is 0.7.0 - install: pretty ✅ TCC output belongs to 'permissions status', not 'check_permissions' (which returns JSON) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
…axes, mcp-config Iteration 1 cross-doc consistency fixes (verified vs live cua-driver 0.7.0): - remove phantom 'screenshot' tool refs (no such tool among the 38) - fix action-response-shape anchor to mcp-tool-notes - explanation index: three axes -> four (adds the action-rung axis) - demonstrations: video is not recorded 'by default' - connect-your-agent: Pi examples need 'call'; mcp-config claude example matches live output (--scope user, no compat flag) Source/generator-level findings (type_text_chars, manifest, flag docs) recorded in DOCS_AUDIT.md for a coordinated fix with cua#2088. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
…versions, autostart, cursor-palette Iteration 2 (macOS how-to guides + recipes, verified vs 0.7.0): - recipes: 'call check_permissions' (JSON) -> 'permissions status' (matches shown output); stale 0.5.x placeholder -> 0.7.0 - keep-running: macOS autostart helper is repo-relative and breaks for curl-installed users; reframed around the plist - personalize-cursor: document the live --cursor-palette launch flag Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
…mpeg, systemd target Iteration 3 (Linux, live-verified on fresh Azure Ubuntu 22.04): - install (Linux): [blocker] binary won't launch without libXi.so.6; add 'sudo apt install libxi6 at-spi2-core' prereq + sudo caveat + headless-desktop note; drop the phantom ffmpeg claim from the doctor sentence - keep-running (Linux): headless boxes need WantedBy=default.target Recorded (generator fix, cua#2088): mcp-tools tool count is platform-specific — Linux exposes 43 (5 Linux-only tools incl type_text_chars), macOS 38. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Iteration 4 (Windows, live on Azure Server 2022 via run-command/Session 0): - install (Windows): note the installer registers the cua-driver-serve autostart task + its interactive requirement - keep-running (Windows): autostart from a non-interactive/SSH context fails with a cryptic SID error — use RDP/local console Windows list-tools = 39 (macOS 38 / Linux 43) — reinforces the platform-specific tool-surface finding for cua#2088. Full audit summary in DOCS_AUDIT.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughDocumentation-only updates across the Cua Driver docs: clarifies that ChangesDocumentation Updates
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The page title is 'Choose an Action Rung and Dispatch Mode' but several docs linked it as 'Choose a capture and dispatch mode'. Unify to match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/docs/how-to-guides/driver/install.mdx (1)
98-107: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winReplace the stale prompt example
Thecua-driver check_permissionsexample is misleading here: from a terminal it falls back to report-only and won’t open the macOS prompts. Usecua-driver permissions granthere, or remove this block since the previous example already covers prompting.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/docs/how-to-guides/driver/install.mdx` around lines 98 - 107, The prompt example in the install guide is stale: `cua-driver check_permissions` from a terminal only reports status and does not open the macOS dialogs. Update the example in the permissions section to use `cua-driver permissions grant` instead, or remove the “trigger the prompts yourself” block if the preceding `cua-driver permissions status` example already covers the flow; keep the surrounding explanation aligned with the actual behavior of the `permissions` commands.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/docs/explanation/capture-and-dispatch-modalities.mdx`:
- Line 63: The reference link for the escalation field is pointing to the wrong
MCP docs page. Update the link in the `capture-and-dispatch-modalities.mdx`
content to use the existing `mcp-tools` reference anchor for
`action-response-shape`, or add an equivalent redirect if you want to keep the
newer path. Keep the surrounding guidance about `escalation`, `px`,
`foreground`, `page`, and the linked ladder doc unchanged.
In `@docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx`:
- Around line 49-55: The example in this recipe is using the wrong command to
trigger the macOS permission prompts; `permissions status` only checks state and
will not prompt the user. Update the flow in the form-filling guide so the first
command uses `cua-driver permissions grant`, then keep `cua-driver permissions
status` as the follow-up verification step after both prompts are approved.
---
Outside diff comments:
In `@docs/content/docs/how-to-guides/driver/install.mdx`:
- Around line 98-107: The prompt example in the install guide is stale:
`cua-driver check_permissions` from a terminal only reports status and does not
open the macOS dialogs. Update the example in the permissions section to use
`cua-driver permissions grant` instead, or remove the “trigger the prompts
yourself” block if the preceding `cua-driver permissions status` example already
covers the flow; keep the surrounding explanation aligned with the actual
behavior of the `permissions` commands.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: da65896c-3384-4911-bf2d-53b9e6be2f80
📒 Files selected for processing (13)
docs/content/docs/explanation/capture-and-dispatch-modalities.mdxdocs/content/docs/explanation/demonstrations-skills-and-trajectories.mdxdocs/content/docs/explanation/index.mdxdocs/content/docs/how-to-guides/driver/connect-your-agent.mdxdocs/content/docs/how-to-guides/driver/install.mdxdocs/content/docs/how-to-guides/driver/keep-running.mdxdocs/content/docs/how-to-guides/driver/personalize-cursor.mdxdocs/content/docs/how-to-guides/driver/update.mdxdocs/content/docs/how-to-guides/driver/windows-ssh.mdxdocs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdxdocs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdxdocs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdxdocs/content/docs/tutorials/drive-your-first-app.mdx
| `effect` is the confidence signal that separates those cases. `"confirmed"` means the driver verified the result through AX read-back. `"unverifiable"` means the dispatch path ran, but the driver cannot prove the application applied it. `"suspected_noop"` means an AX action dispatched but almost certainly did not change the target. Callers should treat `effect`, not the transport-level success status, as the action outcome. | ||
|
|
||
| `escalation` is the machine-readable climb-the-ladder hint. When present, it tells the caller which surface to try next: `"px"` for acting off the screenshot, `"foreground"` for explicitly fronting the target, or `"page"` for the browser-tab DOM path through the `page` tool. See [Choose an action rung and dispatch mode](/how-to-guides/driver/choose-a-modality) for the procedural ladder and [MCP tools](/reference/cua-driver/mcp-tools#action-response-shape) for the field table. | ||
| `escalation` is the machine-readable climb-the-ladder hint. When present, it tells the caller which surface to try next: `"px"` for acting off the screenshot, `"foreground"` for explicitly fronting the target, or `"page"` for the browser-tab DOM path through the `page` tool. See [Choose an action rung and dispatch mode](/how-to-guides/driver/choose-a-modality) for the procedural ladder and [MCP tool notes](/reference/cua-driver/mcp-tool-notes#action-response-shape) for the field table. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check for mcp-tool-notes.mdx and the action-response-shape anchor
fd -i 'mcp-tool-notes' docs
rg -n 'action-response-shape|Action response shape' docs/content/docs/reference/cua-driver/Repository: trycua/cua
Length of output: 230
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the relevant docs tree and look for any redirect/alias from mcp-tools to mcp-tool-notes.
find docs/content/docs/reference/cua-driver -maxdepth 1 -type f | sort
echo '---'
rg -n --hidden --glob '!**/node_modules/**' 'mcp-tool-notes|mcp-tools|redirect|aliases|slug' docs/content/docs/reference/cua-driver docs/content/docs -g '*.mdx' -g '*.md'Repository: trycua/cua
Length of output: 3550
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '--- meta.json ---'
cat -n docs/content/docs/reference/cua-driver/meta.json
echo '--- redirects / aliases search ---'
rg -n --hidden --glob '!**/node_modules/**' 'mcp-tool-notes|mcp-tools|redirect|alias|aliases|slug' docs . -g 'meta.json' -g '*.json' -g '*.mdx' -g '*.md'Repository: trycua/cua
Length of output: 11396
Keep the action-response-shape link on mcp-tools
docs/content/docs/explanation/capture-and-dispatch-modalities.mdx:63 points to /reference/cua-driver/mcp-tool-notes#action-response-shape, but the Cua Driver docs still expose mcp-tools.mdx as the reference page and ## Action response shape lives there. Point the link back to /reference/cua-driver/mcp-tools#action-response-shape or add a matching redirect/page.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/docs/explanation/capture-and-dispatch-modalities.mdx` at line
63, The reference link for the escalation field is pointing to the wrong MCP
docs page. Update the link in the `capture-and-dispatch-modalities.mdx` content
to use the existing `mcp-tools` reference anchor for `action-response-shape`, or
add an equivalent redirect if you want to keep the newer path. Keep the
surrounding guidance about `escalation`, `px`, `foreground`, `page`, and the
linked ladder doc unchanged.
Comment on lines
+49
to
+55
| cua-driver permissions status | ||
| ``` | ||
|
|
||
| Approve both prompts, then run the check again: | ||
|
|
||
| ```bash | ||
| cua-driver call check_permissions | ||
| cua-driver permissions status |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,120p' docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx
printf '\n--- SEARCH ---\n'
rg -n "cua-driver permissions (status|grant)" docs . -g '!**/node_modules/**' -g '!**/dist/**' -g '!**/build/**'Repository: trycua/cua
Length of output: 8936
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '356,366p' docs/content/docs/reference/cua-driver/cli-reference.mdx
printf '\n---\n'
sed -n '88,116p' docs/content/docs/how-to-guides/driver/install.mdx
printf '\n---\n'
sed -n '28,38p' docs/content/docs/tutorials/drive-your-first-app.mdxRepository: trycua/cua
Length of output: 1591
Use permissions grant before rechecking
permissions status is read-only and won’t trigger the macOS prompts. Start with permissions grant, then run permissions status to confirm both permissions are granted.
Suggested fix
```bash
-cua-driver permissions status
+cua-driver permissions grantApprove both prompts, then run the check again:
cua-driver permissions status
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx`
around lines 49 - 55, The example in this recipe is using the wrong command to
trigger the macOS permission prompts; `permissions status` only checks state and
will not prompt the user. Update the flow in the form-filling guide so the first
command uses `cua-driver permissions grant`, then keep `cua-driver permissions
status` as the follow-up verification step after both prompts are approved.
…grant recipe - capture-and-dispatch-modalities: mcp-tool-notes doesn't exist on main (it's introduced by #2088), so point action-response-shape back to mcp-tools - fill-a-form recipe: 'permissions status' is read-only and won't trigger the prompts the step tells you to approve — use 'permissions grant' first Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Now that #2088 has merged, the 'Action response shape' section lives in mcp-tool-notes.mdx (moved out of the auto-generated mcp-tools.mdx). Point the capture-and-dispatch-modalities link at its new home. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Walked the cua-driver docs end-to-end as a new user — install → tutorial → how-to → recipes → reference → explanation — running every documented command against live cua-driver 0.7.0 on macOS (local, full drive loop), Linux (Azure Ubuntu 22.04), and Windows (Azure Server 2022). This PR fixes the hand-written-doc issues found. 13 files, no auto-generated docs touched.
Highlights
libXi.so.6missing); docs listed no apt prereqs and claimed "no admin access." Addedsudo apt install libxi6 at-spi2-core+ the sudo caveat + a note that headless servers have no desktop to drive.--scope userand no longer emits--claude-code-computer-use-compat.screenshottool references (no such tool on any platform); fixed theaction-response-shapeanchor; "three axes" → four; the video-"by default" contradiction; recipecall check_permissions(JSON) →permissions status.cua-driver-serveautostart task, and thatautostart enablefrom a non-interactive/SSH context fails with a cryptic SID error.0.3.x/0.5.x→0.7.0).Verified live (no fix needed)
Full macOS drive loop (launch_app → get_window_state → click by element_index → 42, no-foreground contract holds); drove a real Chrome tab via the
pagetool; cursor/recording/modality flags matchdescribe; Linux install layout + serve lifecycle afterlibxi6; Windows install one-liner + paths + serve/status/stop.Left for follow-up (NOT in this PR)
Generator (coordinate with #2088 — the reference is auto-generated from one platform): the tool surface is platform-specific — macOS 38 / Linux 43 / Windows 39 tools.
mcp-tools.mdxshould emit per-platform tools (incl. the Linux-onlytype_text_charsthatset_valuereferences) with a correct count;cli-reference.mdxis missingmanifest, overstates the now-inert compat flag, and omits theserve/mcpcursor + pip flags (dump-docsreportsserve args: []).Upstream binary (not docs): the Windows/Linux
doctorwarning string names a nonexistentscreenshottool;autostart enableshould detect Session 0 and print a friendly message;recording renderhelp advertises--outputbut takes a positional arg.🤖 Generated with Claude Code
Summary by CodeRabbit