feat(skills): port Skills/ to cua-driver-rs + add WINDOWS.md/LINUX.md + deploy at install time - #1553
Conversation
…md / LINUX.md
Drop the macOS Skills/cua-driver/ tree into libs/cua-driver-rs/Skills/cua-driver-rs/ verbatim, then add platform-specific carve-outs for the cross-platform port:
- `SKILL.md` — top-of-file platform-reading banner pointing Windows / Linux agents at the right carve-out. `name:` updated to `cua-driver-rs`. Body unchanged from the macOS source (still macOS-skewed; full shared-core extraction is a follow-up).
- `WINDOWS.md` — new, 686 lines. Windows-specific carve-out covering:
- No-foreground contract w/ Windows forbidden-list (`Start-Process`, `SetForegroundWindow`, `SwitchToThisWindow`, `cmd /c start`, `explorer.exe shell:AppsFolder\\…`, `AttachThreadInput` tricks, `SendInput`, Chromium `Ctrl+L` / `Ctrl+T` / `Ctrl+1..9`, Win+key shell shortcuts).
- Intent → tool mapping table with Windows analogs.
- CLI argument plumbing on Windows (stdin pipe vs argv quoting; PowerShell 5.1 limitations).
- Prerequisites including the Session 0 vs Session 1+ distinction (UIA/screenshot fail silently in Session 0; daemon must run via the LogonType=Interactive Scheduled Task, not via SSH-into-Windows).
- Click semantics: `element_index` mode = UIA Invoke; `(x,y)` mode = layered UIA hit-test in target HWND subtree → PostMessage fallback. Right-click and count>1 skip UIA Invoke per design.
- UWP / packaged apps section: AUMID resolution, `ApplicationFrameHost.exe` cross-process hosting, Win11 Calc/Notepad/Settings AUMIDs.
- Web apps on Windows section: Edge/Chrome via `launch_app({urls})`, forbidden browser shortcuts table, tabs-vs-windows pattern, WebView2 in non-browser hosts.
- Common failure modes (Session 0, stale HWND, "Posted click" success messages on UWP that didn't actually click, browser tab-switch leak, AUMID resolution, cold-launch HWND race).
- Diagnostics via `cua-driver doctor` and `autostart status`.
- Recording: not-yet-supported note.
- `LINUX.md` — new, 84 lines. Status placeholder. Marks the Linux backend as BETA, documents the X11/Wayland split, lists what works today and what doesn't.
- `README.md` — updated header + Files section to reflect cross-platform structure; the WEB_APPS.md note now flags that Windows web-apps content lives in WINDOWS.md instead.
`WEB_APPS.md`, `RECORDING.md`, `TESTS.md` — copied verbatim from the macOS skill. WEB_APPS.md remains macOS-only for now (Windows web-apps coverage is in WINDOWS.md's "Web apps on Windows" section). Refactoring `SKILL.md` into a shared core + `MACOS.md` adjunct is planned as a follow-up PR (PR B in the design split discussed in #1551 thread); this PR (PR A) ships the Windows carve-out without disrupting macOS workflows.
Install plumbing (drop Skills/ at install time, expose via `cua-driver doctor`, optional `cua-driver skills install` verb) is also a follow-up.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
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:
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for the Changescua-driver-rs Skill Documentation Suite
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsGit: Failed to clone repository. Please run the 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (3)
libs/cua-driver-rs/Skills/cua-driver-rs/LINUX.md (1)
14-21: 💤 Low valueConsider clarifying the Windows SendInput comparison.
The comparison to "Windows
SendInput" on line 18 is technically accurate (both XTest and SendInput steal focus), but readers might wonder why this matters. Consider adding brief context that Windows cua-driver avoids SendInput by using PostMessage for the no-foreground contract, which clarifies why XTest's focus-stealing behavior is a limitation.✏️ Optional clarity improvement
`XTestFakeButtonEvent` synthesize input but route to the focused - window — same focus-steal characteristics as Windows `SendInput`. + window (similar focus-stealing behavior to Windows `SendInput`, + which the Windows backend avoids by using `PostMessage` instead). AT-SPI `accDoDefaultAction` works for accessible elements but🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/LINUX.md` around lines 14 - 21, Update the X11 vs Windows comparison to explain why "focus-stealing" matters: mention that XTestFakeKeyEvent / XTestFakeButtonEvent synthesize input and steal focus similar to Windows SendInput, but on Windows the cua-driver avoids SendInput when implementing the "no-foreground contract" by using PostMessage (e.g., PostMessage(WM_LBUTTONDOWN)) to target a specific window without changing focus; reference XTestFakeKeyEvent, XTestFakeButtonEvent, SendInput, and PostMessage in the LINUX.md paragraph and add one short sentence noting that this difference is why XTest's focus-stealing behavior is a limitation.libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md (1)
1-4: ⚡ Quick winAdd platform scope banner for clarity.
This document is macOS-specific (referencing CGEvent, SLEventPostToPid, AppleScript, etc.) but only mentions "macOS" in passing on line 4. Given that this PR introduces platform-specific carve-outs (WINDOWS.md, LINUX.md), consider adding a prominent platform banner at the top similar to the approach in other platform docs to immediately signal scope.
📝 Suggested banner
# Driving web-rendered apps +> **Platform:** This guide is macOS-specific. For Windows or Linux web automation guidance, see the platform sections in WINDOWS.md and LINUX.md. + Covers apps whose UI is rendered in a web runtime inside a native macOS shell:🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md` around lines 1 - 4, Add a prominent platform scope banner at the top of the "Driving web-rendered apps" document to clearly indicate this doc is macOS-specific; update the heading "Driving web-rendered apps" (and nearby references to CGEvent, SLEventPostToPid, AppleScript) to include a short macOS banner or note in the same style used in other platform docs so readers immediately see the scope. Ensure the banner is placed before the first paragraph and uses the same phrasing/format as the existing platform banners in WINDOWS.md / LINUX.md for consistency.libs/cua-driver-rs/Skills/cua-driver-rs/README.md (1)
22-36: ⚡ Quick winAdd platform qualifiers or generalize macOS-specific implementation details.
Lines 26-28 mention "yabai focus-without-raise + stamped SLEventPostToPid" which are macOS-specific implementation details. Since this README introduces the skill as cross-platform (lines 3-9), readers on Windows/Linux will find these technical details confusing or misleading.
Consider either:
- Adding a platform qualifier: "(on macOS: yabai focus-without-raise...)"
- Generalizing the description: "The backgrounded-click recipe that lets synthetic clicks land on web content without raising the window or pulling the user across virtual desktops."
📝 Proposed fix to generalize platform-specific details
- The snapshot-before-AND-after invariant that keeps the agent honest about whether an action actually landed. -- The backgrounded-click recipe (yabai focus-without-raise + stamped - SLEventPostToPid) that lets synthetic clicks land on Chrome web - content without raising the window or pulling the user across Spaces. +- The backgrounded-click recipe that lets synthetic clicks land on web + content without raising the window or pulling the user across virtual + desktops (macOS: yabai focus-without-raise + SLEventPostToPid).🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md` around lines 22 - 36, In the "What the skill covers" section, update the backgrounded-click bullet (the line mentioning "yabai focus-without-raise + stamped SLEventPostToPid") to avoid macOS-only jargon: either add a platform qualifier such as "(on macOS: yabai focus-without-raise + stamped SLEventPostToPid)" or replace the phrase with a generalized description like "the backgrounded-click recipe that lets synthetic clicks land on web content without raising the window or pulling the user across virtual desktops"; modify the README.md bullet text for clarity so it matches the cross-platform framing used elsewhere in the file.
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md`:
- Around line 147-160: Update the README instruction that copies the skill:
replace the old path string "libs/cua-driver/Skills/cua-driver" with the correct
"libs/cua-driver-rs/Skills/cua-driver-rs" so the cp command copies from the
cua-driver-rs directory; modify the line in README.md under the "Updates"
section where the copy instruction appears to use the corrected path.
- Around line 89-98: Update the "Invoking the skill" section in README.md to
reflect the cross-platform scope (replace the phrase "macOS GUI automation" with
a neutral term like "GUI automation" or "cross-platform GUI automation") and
change the explicit invocation command from "/cua-driver" to match the skill
frontmatter name "cua-driver-rs" (use "/cua-driver-rs"); locate the section
titled "Invoking the skill" in README.md and the SKILL.md frontmatter name
"cua-driver-rs" to ensure the invocation string and platform description are
consistent across docs.
- Around line 65-87: Update the README install paths that incorrectly reference
"Skills/cua-driver" to the correct "Skills/cua-driver-rs" variants: replace
occurrences in the Personal scope, symlink example, and Project scope so cp and
ln commands point to Skills/cua-driver-rs and create
~/.claude/skills/cua-driver-rs (or .claude/skills/cua-driver-rs for project
scope) instead of the non-existent cua-driver directory; ensure the symlink
target and copied source paths consistently use "cua-driver-rs".
- Around line 39-63: The Prerequisites section currently lists macOS-only
requirements under the general "Prerequisites" heading which contradicts the
README intro claiming macOS/Windows/Linux support; update the README.md
Prerequisites block to clearly separate platform-specific instructions by adding
distinct subsections (e.g., "macOS Prerequisites", "Windows Prerequisites",
"Linux Prerequisites") and move the macOS items (macOS 14 requirement,
CuaDriver.app install steps, TCC grants and cua-driver check_permissions) under
"macOS Prerequisites", then add brief notes under "Windows Prerequisites" and
"Linux Prerequisites" pointing to new platform docs (e.g., WINDOWS.md, LINUX.md)
or to BETA caveats so Windows/Linux users aren’t misled and can find
platform-specific installation/permissions guidance.
In `@libs/cua-driver-rs/Skills/cua-driver-rs/RECORDING.md`:
- Around line 1-5: Add a clear platform-availability caveat to the top of the
"Recording & replaying trajectories" doc and the "replay" section stating that
recording and replay are currently macOS-only (or otherwise platform-limited),
and include explicit pointer links to WINDOWS.md and LINUX.md so users on those
platforms know recording is unsupported and where to find alternatives; update
the intro paragraph under the "Recording & replaying trajectories" heading and
the replay subsection (the blocks around the current replay instructions) to
include this note and the two file links.
In `@libs/cua-driver-rs/Skills/cua-driver-rs/TESTS.md`:
- Around line 1-17: Add a short header to TESTS.md clarifying that the test
suite is macOS-focused and not universal: explicitly state that
prompts/assertions reference AppKit, NSWorkspace.frontmostApplication, and macOS
keyboard modifiers (e.g., cmd) and should only be run on macOS; then either add
links to or stub sections for Windows/Linux carve-outs (or instructions for
platform-specific variants) so reviewers running on non-macOS platforms know to
skip or use the alternate tests.
In `@libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md`:
- Around line 417-431: The AppleScript snippet calls tell application "Safari"
to activate which violates the no-foreground contract referenced in SKILL.md;
update the WEB_APPS.md entry to either (A) explicitly document this AppleScript
as an exception requiring explicit user consent and callout the foreground
impact (referencing the "tell application \"Safari\" to activate" line and the
surrounding script), or (B) remove that activation from the example and instead
state clearly that enabling "Allow JavaScript from Apple Events" for Safari
cannot be automated without breaking the contract and must be performed manually
by the user; make the chosen approach obvious next to the snippet and adjust the
comment on line ~419 to match.
- Around line 304-319: The documentation asserts fixed Chrome sync timing
windows and uses a hardcoded sleep (sleep 5) after open -a "Google Chrome" which
can cause flaky tests; update the prose around the osascript/Chrome launch
section to use qualified language (e.g., "typically" or "may") instead of
definitive timings and either increase the sleep to a more conservative default
or replace the single sleep 5 with a documented retry/wait approach (e.g.,
looped checks using the same osascript snippet until a stable expected value is
observed or a timeout is reached) so the guidance and the launch + verify
sequence (open -a "Google Chrome", sleep 5, the osascript execute javascript
block) reflect environment-dependent behavior.
---
Nitpick comments:
In `@libs/cua-driver-rs/Skills/cua-driver-rs/LINUX.md`:
- Around line 14-21: Update the X11 vs Windows comparison to explain why
"focus-stealing" matters: mention that XTestFakeKeyEvent / XTestFakeButtonEvent
synthesize input and steal focus similar to Windows SendInput, but on Windows
the cua-driver avoids SendInput when implementing the "no-foreground contract"
by using PostMessage (e.g., PostMessage(WM_LBUTTONDOWN)) to target a specific
window without changing focus; reference XTestFakeKeyEvent,
XTestFakeButtonEvent, SendInput, and PostMessage in the LINUX.md paragraph and
add one short sentence noting that this difference is why XTest's focus-stealing
behavior is a limitation.
In `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md`:
- Around line 22-36: In the "What the skill covers" section, update the
backgrounded-click bullet (the line mentioning "yabai focus-without-raise +
stamped SLEventPostToPid") to avoid macOS-only jargon: either add a platform
qualifier such as "(on macOS: yabai focus-without-raise + stamped
SLEventPostToPid)" or replace the phrase with a generalized description like
"the backgrounded-click recipe that lets synthetic clicks land on web content
without raising the window or pulling the user across virtual desktops"; modify
the README.md bullet text for clarity so it matches the cross-platform framing
used elsewhere in the file.
In `@libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md`:
- Around line 1-4: Add a prominent platform scope banner at the top of the
"Driving web-rendered apps" document to clearly indicate this doc is
macOS-specific; update the heading "Driving web-rendered apps" (and nearby
references to CGEvent, SLEventPostToPid, AppleScript) to include a short macOS
banner or note in the same style used in other platform docs so readers
immediately see the scope. Ensure the banner is placed before the first
paragraph and uses the same phrasing/format as the existing platform banners in
WINDOWS.md / LINUX.md for consistency.
🪄 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: b2688589-ba53-4cdd-bf0d-e31528bdd72c
📒 Files selected for processing (7)
libs/cua-driver-rs/Skills/cua-driver-rs/LINUX.mdlibs/cua-driver-rs/Skills/cua-driver-rs/README.mdlibs/cua-driver-rs/Skills/cua-driver-rs/RECORDING.mdlibs/cua-driver-rs/Skills/cua-driver-rs/SKILL.mdlibs/cua-driver-rs/Skills/cua-driver-rs/TESTS.mdlibs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.mdlibs/cua-driver-rs/Skills/cua-driver-rs/WINDOWS.md
| ## Prerequisites | ||
|
|
||
| 1. **macOS 14 or newer** — the driver depends on SkyLight private SPIs | ||
| that were stabilized in Sonoma. | ||
| 2. **`cua-driver` CLI + `CuaDriver.app`** — installable one-liner: | ||
| ```bash | ||
| /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)" | ||
| ``` | ||
| Or from a clone of `trycua/cua`: | ||
| ```bash | ||
| cd libs/cua-driver | ||
| scripts/install-local.sh # builds + installs + symlinks for dev use | ||
| ``` | ||
| The driver runs as an `.app` bundle because macOS TCC grants are | ||
| tied to a stable bundle id (`com.trycua.driver`). The CLI symlink | ||
| lets Claude invoke tools via plain shell. | ||
| 3. **TCC grants on `CuaDriver.app`** — **Accessibility** and | ||
| **Screen Recording** in System Settings → Privacy & Security. | ||
| Verify with: | ||
| ```bash | ||
| cua-driver check_permissions | ||
| ``` | ||
| Both fields must be `true`. If not, the app appears in the | ||
| relevant panes of System Settings after first use; toggle it on | ||
| there. |
There was a problem hiding this comment.
Prerequisites section contradicts cross-platform claims.
The introduction (lines 3-9) describes this skill as supporting macOS, Windows, and Linux. However, the Prerequisites section (lines 39-63) presents macOS-only requirements as if they're universal:
- Line 41: "macOS 14 or newer" (excludes Windows/Linux)
- Lines 43-63: CuaDriver.app, TCC grants (macOS-specific)
Windows and Linux users reading this will incorrectly conclude the skill doesn't support their platform.
📋 Proposed fix to clarify platform-specific prerequisites
## Prerequisites
+### macOS Prerequisites
+
1. **macOS 14 or newer** — the driver depends on SkyLight private SPIs
that were stabilized in Sonoma.
2. **`cua-driver` CLI + `CuaDriver.app`** — installable one-liner:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"
```
+
+### Windows Prerequisites
+
+See `WINDOWS.md` for Windows-specific installation and permissions.
+
+### Linux Prerequisites
+
+See `LINUX.md` for Linux-specific installation and setup (BETA).🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md` around lines 39 - 63, The
Prerequisites section currently lists macOS-only requirements under the general
"Prerequisites" heading which contradicts the README intro claiming
macOS/Windows/Linux support; update the README.md Prerequisites block to clearly
separate platform-specific instructions by adding distinct subsections (e.g.,
"macOS Prerequisites", "Windows Prerequisites", "Linux Prerequisites") and move
the macOS items (macOS 14 requirement, CuaDriver.app install steps, TCC grants
and cua-driver check_permissions) under "macOS Prerequisites", then add brief
notes under "Windows Prerequisites" and "Linux Prerequisites" pointing to new
platform docs (e.g., WINDOWS.md, LINUX.md) or to BETA caveats so Windows/Linux
users aren’t misled and can find platform-specific installation/permissions
guidance.
| ## Install | ||
|
|
||
| The skill is two drop-in directories. | ||
|
|
||
| **Personal scope** (all Claude Code sessions on your machine): | ||
|
|
||
| ```bash | ||
| mkdir -p ~/.claude/skills | ||
| cp -R Skills/cua-driver ~/.claude/skills/ | ||
| ``` | ||
|
|
||
| Or symlink if you want edits-in-place: | ||
|
|
||
| ```bash | ||
| ln -s "$PWD/Skills/cua-driver" ~/.claude/skills/cua-driver | ||
| ``` | ||
|
|
||
| **Project scope** (committed alongside a specific repo): | ||
|
|
||
| ```bash | ||
| mkdir -p .claude/skills | ||
| cp -R /path/to/cua/libs/cua-driver/Skills/cua-driver .claude/skills/ | ||
| ``` |
There was a problem hiding this comment.
Correct installation paths to use cua-driver-rs directory name.
All installation commands reference Skills/cua-driver but the actual directory structure (per PR objectives and file paths) is Skills/cua-driver-rs. Users following these instructions will attempt to copy from a non-existent path or create incorrectly-named skill directories.
🔧 Proposed fix for installation paths
**Personal scope** (all Claude Code sessions on your machine):
```bash
mkdir -p ~/.claude/skills
-cp -R Skills/cua-driver ~/.claude/skills/
+cp -R Skills/cua-driver-rs ~/.claude/skills/Or symlink if you want edits-in-place:
-ln -s "$PWD/Skills/cua-driver" ~/.claude/skills/cua-driver
+ln -s "$PWD/Skills/cua-driver-rs" ~/.claude/skills/cua-driver-rsProject scope (committed alongside a specific repo):
mkdir -p .claude/skills
-cp -R /path/to/cua/libs/cua-driver/Skills/cua-driver .claude/skills/
+cp -R /path/to/cua/libs/cua-driver-rs/Skills/cua-driver-rs .claude/skills/</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
## Install
The skill is two drop-in directories.
**Personal scope** (all Claude Code sessions on your machine):
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md` around lines 65 - 87,
Update the README install paths that incorrectly reference "Skills/cua-driver"
to the correct "Skills/cua-driver-rs" variants: replace occurrences in the
Personal scope, symlink example, and Project scope so cp and ln commands point
to Skills/cua-driver-rs and create ~/.claude/skills/cua-driver-rs (or
.claude/skills/cua-driver-rs for project scope) instead of the non-existent
cua-driver directory; ensure the symlink target and copied source paths
consistently use "cua-driver-rs".
| ## Invoking the skill | ||
|
|
||
| Claude Code auto-invokes the skill when you ask for macOS GUI | ||
| automation — e.g. "open the Downloads folder in Finder", "click the | ||
| Save button in Numbers", "navigate to trycua.com in Chrome". You can | ||
| also invoke it explicitly: | ||
|
|
||
| ``` | ||
| /cua-driver | ||
| ``` |
There was a problem hiding this comment.
Update platform references and invocation command to match cross-platform scope.
Line 92 mentions "macOS GUI automation" exclusively, contradicting the cross-platform introduction. Line 97 shows /cua-driver but the skill's frontmatter name (SKILL.md line 2) is cua-driver-rs.
📝 Proposed fixes
## Invoking the skill
-Claude Code auto-invokes the skill when you ask for macOS GUI
-automation — e.g. "open the Downloads folder in Finder", "click the
-Save button in Numbers", "navigate to trycua.com in Chrome". You can
-also invoke it explicitly:
+Claude Code auto-invokes the skill when you ask for native GUI
+automation — e.g. "open the Downloads folder in Finder" (macOS),
+"click the Save button in Notepad" (Windows), "open System Settings"
+(Linux). You can also invoke it explicitly:
-/cua-driver
+/cua-driver-rs
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/README.md` around lines 89 - 98,
Update the "Invoking the skill" section in README.md to reflect the
cross-platform scope (replace the phrase "macOS GUI automation" with a neutral
term like "GUI automation" or "cross-platform GUI automation") and change the
explicit invocation command from "/cua-driver" to match the skill frontmatter
name "cua-driver-rs" (use "/cua-driver-rs"); locate the section titled "Invoking
the skill" in README.md and the SKILL.md frontmatter name "cua-driver-rs" to
ensure the invocation string and platform description are consistent across
docs.
| ## Updates | ||
|
|
||
| The skill evolves alongside the driver. To update: | ||
|
|
||
| ```bash | ||
| cd /path/to/cua && git pull | ||
| # if you copied: re-copy | ||
| cp -R libs/cua-driver/Skills/cua-driver ~/.claude/skills/ | ||
| # if you symlinked: nothing needed | ||
| ``` | ||
|
|
||
| ## License | ||
|
|
||
| MIT. Same license as the parent `trycua/cua` repo. |
There was a problem hiding this comment.
Correct update instructions to use cua-driver-rs path.
Line 154 references the old libs/cua-driver/Skills/cua-driver path instead of libs/cua-driver-rs/Skills/cua-driver-rs.
🔧 Proposed fix
## Updates
The skill evolves alongside the driver. To update:
```bash
cd /path/to/cua && git pull
# if you copied: re-copy
-cp -R libs/cua-driver/Skills/cua-driver ~/.claude/skills/
+cp -R libs/cua-driver-rs/Skills/cua-driver-rs ~/.claude/skills/
# if you symlinked: nothing needed</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @libs/cua-driver-rs/Skills/cua-driver-rs/README.md around lines 147 - 160,
Update the README instruction that copies the skill: replace the old path string
"libs/cua-driver/Skills/cua-driver" with the correct
"libs/cua-driver-rs/Skills/cua-driver-rs" so the cp command copies from the
cua-driver-rs directory; modify the line in README.md under the "Updates"
section where the copy instruction appears to use the corrected path.
</details>
<!-- fingerprinting:phantom:triton:puma -->
<!-- This is an auto-generated comment by CodeRabbit -->
| # Recording & replaying trajectories | ||
|
|
||
| Session-scoped capture of action sequences + pre/post state, suitable | ||
| for demos, regression diffs, and training data. Invoked only when the | ||
| user explicitly asks to record — the skill does not auto-enable this. |
There was a problem hiding this comment.
Add explicit platform availability caveat for recording/replay.
This doc reads as universally supported, but the stack context indicates recording is not supported on Windows and Linux yet. Please add a clear note near the top (and in replay section) that recording/replay is currently macOS-only (or platform-limited), with pointers to WINDOWS.md / LINUX.md to avoid failed user workflows.
Also applies to: 15-20, 81-87
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/RECORDING.md` around lines 1 - 5, Add
a clear platform-availability caveat to the top of the "Recording & replaying
trajectories" doc and the "replay" section stating that recording and replay are
currently macOS-only (or otherwise platform-limited), and include explicit
pointer links to WINDOWS.md and LINUX.md so users on those platforms know
recording is unsupported and where to find alternatives; update the intro
paragraph under the "Recording & replaying trajectories" heading and the replay
subsection (the blocks around the current replay instructions) to include this
note and the two file links.
| # Natural-language tests for `cua-driver` | ||
|
|
||
| Prompts you can copy-paste into Claude Code to exercise the skill | ||
| end-to-end. Each one has an explicit success criterion you can verify. | ||
|
|
||
| Check off as you go. Mark ❌ + a short note when something regresses. | ||
|
|
||
| **Global invariants that apply to every test (unless otherwise | ||
| noted):** no focus flash, cursor doesn't move, the target app stays | ||
| backgrounded throughout, and Claude uses the canonical | ||
| `launch_app → get_window_state → act → get_window_state → verify` loop | ||
| (never shells out to `open -a`, never calls `simulate_click` or | ||
| `click_at` as a fallback). | ||
|
|
||
| --- | ||
|
|
||
| ## Native AppKit targets |
There was a problem hiding this comment.
Clarify platform scope at the top of this test plan.
This file currently reads as universal, but most prompts/assertions are macOS-specific (e.g., NSWorkspace.frontmostApplication, AppKit targets, cmd shortcuts). In a cross-platform skill bundle, please add a short header note that this suite is macOS-focused and link to Windows/Linux carve-outs (or add parallel sections) to avoid running invalid tests on those platforms.
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/TESTS.md` around lines 1 - 17, Add a
short header to TESTS.md clarifying that the test suite is macOS-focused and not
universal: explicitly state that prompts/assertions reference AppKit,
NSWorkspace.frontmostApplication, and macOS keyboard modifiers (e.g., cmd) and
should only be run on macOS; then either add links to or stub sections for
Windows/Linux carve-outs (or instructions for platform-specific variants) so
reviewers running on non-macOS platforms know to skip or use the alternate
tests.
| # 3. Relaunch Chrome and wait for sync to stabilise. | ||
| # Chrome sync fires ~1-2 s after launch and may briefly pull | ||
| # an older value from the server before Chrome pushes our local | ||
| # True back. Either test before sync fires (<1 s) or after it | ||
| # settles (>4 s). Waiting exactly ~2 s lands in the race window | ||
| # and is the most likely way to see a false negative. | ||
| open -a "Google Chrome" | ||
| sleep 5 | ||
|
|
||
| # 4. Verify | ||
| osascript -e 'tell application "Google Chrome" | ||
| tell active tab of front window | ||
| execute javascript "1+1" | ||
| end tell | ||
| end tell' | ||
| # → 2 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -type f -name "WEB_APPS.md" | head -20Repository: trycua/cua
Length of output: 156
🌐 Web query:
Chrome sync timing after launch seconds official documentation
💡 Result:
There is no single, publicly documented "official" number of seconds that Chrome waits after launch before initiating a sync operation. Chrome’s synchronization engine is designed to be dynamic and event-driven rather than strictly time-based [1][2]. Key aspects of Chrome sync timing include: 1. Event-Driven Synchronization: Chrome sync is primarily triggered by changes to data (e.g., adding a bookmark, updating a password, or opening a new tab) [3][2]. When such an event occurs, the browser attempts to propagate the change to the server and other devices as soon as possible [2]. 2. Background Operations: Upon browser launch, Chrome performs a "check-in" with the sync servers to reconcile the local state with the cloud state [2]. This process is generally designed to be near-instantaneous for typical data volumes [4]. 3. Performance Optimization: Chrome prioritizes browser responsiveness over immediate synchronization [5]. If the browser is under heavy load or network conditions are poor, sync operations may be queued or throttled to avoid impacting the user experience [5]. 4. Diagnostic Tools: For users or administrators needing to investigate sync timing or latency, Google provides the internal page chrome://sync-internals/ [6][7]. This tool allows you to view the sync engine's status, trace specific operations, and monitor for errors or delays in real-time [6]. While some third-party technical guides suggest that healthy sync cycles typically complete in under 500 milliseconds [5] and that specific configurations can influence startup latency [6], these are not official Google-specified timing constants. If you are experiencing significant delays, it is typically attributed to network issues, large data payloads, or local profile corruption rather than a fixed startup delay [5][6][8].
Citations:
- 1: https://support.google.com/chrome/a/answer/13616205?hl=en
- 2: https://www.chromethemer.com/chrome-account-sync-settings/
- 3: https://knowledge.workspace.google.com/admin/reports/chrome-sync-log-events
- 4: https://www.reddit.com/r/browsers/comments/1q5jxvp/chrome_says_its_syncing_but_its_been_over_an_hour/
- 5: https://claudecodeguides.com/chrome-sync-slowing-browser/
- 6: https://lifetips.alibaba.com/tech-efficiency/having-problems-with-google-sync
- 7: https://www.cyberengage.org/post/understanding-chrome-synchronization-a-digital-forensics-perspective
- 8: https://superuser.com/questions/277656/google-chrome-is-taking-forever-to-set-up-sync
🌐 Web query:
Google Chrome sync behavior timing race condition
💡 Result:
Google Chrome Sync is designed as a distributed system that prioritizes eventual consistency, allowing users to modify data across multiple devices simultaneously without requiring a constant, synchronous connection to the server [1][2]. Because of this architecture, race conditions are a fundamental challenge that the system manages through specific conflict resolution strategies and data structures rather than strict global locking [3][1][4]. Key mechanisms for managing sync behavior and race conditions include: Conflict Resolution: When a conflict occurs—such as when a client has a pending local change while simultaneously receiving an update for the same entity from the server—the system employs a default conflict resolution strategy [3]. While the specific implementation can be customized by data type bridges, the system generally aims to resolve these conflicts automatically without user intervention [1]. Merging of data during conflict resolution is not currently supported; the system typically chooses between keeping the local pending change or applying the remote update [3]. Prevention of Ping-Pong Effects: To avoid "ping-pong" issues, where multiple clients continuously overwrite each other's changes due to differing interpretations of the "correct" state, developers are advised to avoid triggering outgoing sync updates directly from incoming sync updates [3]. Instead, best practices suggest fixing data locally without committing it, allowing the next natural change to propagate the fix, or implementing rate-limiting if a re-upload is strictly necessary [3]. Unique Positions: For ordered data types (like bookmarks), Chrome Sync uses a "Unique Position" API [5]. This approach uses globally unique identifiers to maintain a consistent, well-defined ordering across all clients [5]. By using these unique positions, the system reduces the likelihood of conflicts that would otherwise arise from index-based ordering, which is highly susceptible to race conditions when multiple clients modify the same list [5]. Architecture and Threading: The sync engine operates on a layered architecture that separates high-level service logic from low-level protocol management [1][2]. It utilizes multiple threads to maintain UI responsiveness, with specific data types (like bookmarks or passwords) often running on dedicated threads [2]. Within the Chromium codebase, developers use standard synchronization primitives, such as mutexes and condition variables, to protect shared state and prevent race conditions during local processing [6]. For developers working with Chrome extensions, the chrome.storage.sync API is managed by the browser's internal sync infrastructure [7][8]. Because this API is asynchronous and operates in a distributed environment, developers must be aware that race conditions can occur if multiple storage operations are performed without proper coordination, as the underlying state may change due to cloud updates [7].
Citations:
- 1: https://chromium.org/developers/design-documents/sync
- 2: https://chromium.googlesource.com/chromium/src/+/lkgr/components/sync
- 3: https://chromium.org/developers/design-documents/sync/sync-data-best-practices
- 4: https://medium.com/@alexglushenkov/the-art-of-staying-in-sync-how-distributed-systems-avoid-race-conditions-f59b58817e02
- 5: https://chromium.org/developers/design-documents/sync/unique-positions
- 6: https://www.chromium.org/developers/lock-and-condition-variable/
- 7: https://stackoverflow.com/questions/15050861/best-way-to-prevent-race-condition-in-multiple-chrome-storage-api-calls
- 8: https://dev.to/codewithahsan/i-built-a-chrome-extension-to-sync-ai-studio-system-instructions-heres-why-chromestoragesync-2llm
🏁 Script executed:
sed -n '304,319p' ./libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.mdRepository: trycua/cua
Length of output: 609
Qualify Chrome sync timing claims with environmental context.
The specific sync timing windows documented here (1-2s launch, 4s+ settle, 2s race condition) lack official Chrome documentation. Chrome sync is event-driven rather than time-based, and timing varies significantly with network conditions, data volume, machine performance, and Chrome version. Presenting these as definitive thresholds could cause flaky test failures across different environments.
Change the language from definitive statements ("Chrome sync fires ~1-2 s after launch") to qualified descriptions ("typically fires within 1-2 s", "usually settles by 4 s") to reflect the empirical and environment-dependent nature of these timings. Alternatively, update sleep 5 to a longer conservative value or add documented fallback logic for timing-sensitive checks.
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md` around lines 304 - 319,
The documentation asserts fixed Chrome sync timing windows and uses a hardcoded
sleep (sleep 5) after open -a "Google Chrome" which can cause flaky tests;
update the prose around the osascript/Chrome launch section to use qualified
language (e.g., "typically" or "may") instead of definitive timings and either
increase the sleep to a more conservative default or replace the single sleep 5
with a documented retry/wait approach (e.g., looped checks using the same
osascript snippet until a stable expected value is observed or a timeout is
reached) so the guidance and the launch + verify sequence (open -a "Google
Chrome", sleep 5, the osascript execute javascript block) reflect
environment-dependent behavior.
| ```applescript | ||
| -- Requires Accessibility permission for the calling process. | ||
| -- Safari must already be running with the Develop menu visible. | ||
| tell application "Safari" to activate | ||
| delay 0.3 | ||
| tell application "System Events" | ||
| tell process "Safari" | ||
| click menu item "Allow JavaScript from Apple Events" of menu 1 ¬ | ||
| of menu bar item "Develop" of menu bar 1 | ||
| delay 0.3 | ||
| -- Safari shows a confirmation dialog — click Allow | ||
| click button "Allow" of window 1 | ||
| end tell | ||
| end tell | ||
| ``` |
There was a problem hiding this comment.
Safari activation violates the no-foreground contract.
Line 420 explicitly activates Safari (tell application "Safari" to activate), which directly violates the no-foreground contract established in SKILL.md and referenced elsewhere in this document (lines 81-83). This activation brings Safari to the front and disrupts the user's current window focus.
The comment on line 419 states "Safari must already be running" but then proceeds to activate it anyway, which is inconsistent with the backgrounded-driving principles applied to Chrome and other browsers throughout this guide.
Consider either:
- Documenting this as an explicit exception to the no-foreground contract with user consent required, or
- Noting that Safari's JS enablement cannot be automated without breaking the contract and must be done manually by the user
The current presentation makes it appear as standard procedure, which could mislead users about the contract guarantees.
🤖 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 `@libs/cua-driver-rs/Skills/cua-driver-rs/WEB_APPS.md` around lines 417 - 431,
The AppleScript snippet calls tell application "Safari" to activate which
violates the no-foreground contract referenced in SKILL.md; update the
WEB_APPS.md entry to either (A) explicitly document this AppleScript as an
exception requiring explicit user consent and callout the foreground impact
(referencing the "tell application \"Safari\" to activate" line and the
surrounding script), or (B) remove that activation from the example and instead
state clearly that enabling "Allow JavaScript from Apple Events" for Safari
cannot be automated without breaking the contract and must be performed manually
by the user; make the chosen approach obvious next to the snippet and adjust the
comment on line ~419 to match.
…ymlinks Wire the skill pack added in #1553 into the installer pipeline so it actually reaches users' machines. Matches the Swift cua-driver install behavior — drop a symlink/junction for each detected agent (Claude Code, Codex, OpenClaw, OpenCode) that auto-loads Anthropic-format SKILL.md skills from a folder. Never overwrites existing user links. ## Changes ### CD workflow (`.github/workflows/cd-rust-cua-driver.yml`) - Linux package step: include `Skills/cua-driver-rs/` at top level of the directory tarball (`cua-driver-rs-<v>-linux-<arch>.tar.gz`). - Windows package step: include `Skills/cua-driver-rs/` at top level of the directory zip. - macOS package step: copy `Skills/cua-driver-rs/` INTO the bundle at `CuaDriverRs.app/Contents/Resources/Skills/cua-driver-rs/` BEFORE codesigning, so the notarized bundle ships with skills baked in. Matches the Swift cua-driver path layout. ### `libs/cua-driver-rs/scripts/install.ps1` - After extracting the release zip, copy `Skills/` from the staged dir into `<versionedDir>/Skills/cua-driver-rs/` so the per-version dir holds the active skill pack. - After the bin/current junctions are wired, drop directory junctions (`mklink /J`) for each detected agent's skills dir. Junctions resolve through `current\Skills\cua-driver-rs`, so upgrades stay transparent. Junctions don't require Developer Mode / admin (same property the bin/current junctions rely on). ### `libs/cua-driver-rs/scripts/install.sh` - **Tarball selection**: Linux now fetches the directory tarball (`cua-driver-rs-<v>-<label>.tar.gz`) instead of the bare-binary tarball, so the skill pack at `<stage>/Skills/cua-driver-rs/` is included. Backward-compat path retained for older bare-binary layouts. - macOS: the `ditto $SRC_APP $APP_DEST` step already copies the skill pack from inside the .app bundle; SKILL_TARGET points there. - Linux: copy `Skills/cua-driver-rs/` from `<stage>` to `<VERSIONED_DIR>/Skills/cua-driver-rs/` next to the binary; SKILL_TARGET points through the `current` symlink. - New `link_skill_into()` helper mirrors the Swift installer's implementation exactly: symlink into `~/.claude/skills`, `~/.agents/skills`, `~/.openclaw/skills`, `~/.config/opencode/skills` for each detected agent. ### `libs/cua-driver-rs/scripts/install-local.{ps1,sh}` - Stage `Skills/cua-driver-rs/` from the repo into the versioned release dir alongside the just-built binary, mirroring what the production install scripts do from the release artifact. - Same agent-detection symlink/junction loop as the production scripts. ## Net effect After install (or auto-update) on any platform: - `~/.claude/skills/cua-driver-rs` → resolves to the active version's Skills dir. - Same for `~/.agents/skills/`, `~/.openclaw/skills/`, `~/.config/opencode/skills/` (each created if its parent agent config exists and the `skills/` subdir is missing). - Agents auto-discover `SKILL.md`, `WINDOWS.md`, `LINUX.md`, `WEB_APPS.md`, `RECORDING.md`, `TESTS.md` on next start. User-side opt-out: don't have any of the four agent config dirs present; the installer silently skips the symlink step. Dev users with hand-rolled symlinks pointing at a working repo: the `if [[ -e $link_path ]]` guard preserves them across re-runs. ## Test plan - [ ] cua-driver-rs release with skills baked into all three tarballs - [ ] Windows: irm | iex install on a fresh VM creates `%USERPROFILE%\.claude\skills\cua-driver-rs` junction - [ ] macOS: install creates `~/.claude/skills/cua-driver-rs` symlink pointing into the .app - [ ] Linux: install creates `~/.claude/skills/cua-driver-rs` symlink pointing through the `current` symlink Builds on #1553 (which added the Skills/cua-driver-rs/ tree). Deferred to a follow-up: `cua-driver skills {path|status|link}` CLI verb and `cua-driver doctor` reporting of skill-install state.
f-trycua
changed the title
|
Update: extended PR with the install-plumbing piece (PR B from the design split) so the skills actually reach users' machines. New commit
Test plan delta:
Deferred to follow-up issue: |
…n install) User feedback on the previous auto-link approach: don't touch ~/.claude/skills/ from the install script. Make it explicit. Match the same shape the user opted into — the verb fetches a versioned release asset from GitHub and symlinks into detected agent dirs. ## Subcommands - `cua-driver skills install` — fetch + place at <HomeDir>/skills/cua-driver-rs + symlink into each detected agent's skills dir. - `cua-driver skills update` — alias for `install --force`; re-fetch and refresh content. - `cua-driver skills uninstall [--all]` — remove agent symlinks; with `--all`, delete the local copy too. - `cua-driver skills status` — read-only probe of local + per-agent state. - `cua-driver skills path` — print the local skill pack path. - `--from main` — bleeding-edge mode: fetch each .md from raw.githubusercontent.com/trycua/cua/main instead of the tagged release. ## Fetch source Default: `https://github.com/trycua/cua/releases/download/cua-driver-rs-v<v>/cua-driver-rs-v<v>-skills.tar.gz` where `<v>` is the binary's own version (`CARGO_PKG_VERSION`). Pins the skill content to the binary release. CD now publishes this tarball as a per-release asset alongside the platform tarballs. ## Agent detection (same 4 the Swift cua-driver wires) - Claude Code: `~/.claude/skills/` - Codex: `~/.agents/skills/` - OpenClaw: `~/.openclaw/skills/` - OpenCode: `~/.config/opencode/skills/` (macOS/Linux), `%APPDATA%\opencode\skills\` (Windows) Only acts when the agent's parent skills dir already exists. Never overwrites an existing `<agent_skills>/cua-driver-rs` link — preserves dev users' hand-rolled symlinks. Windows uses `mklink /J` (no admin/devmode); macOS/Linux use `ln -s`. ## Install scripts revert Previously this branch had auto-link logic in install.ps1 / install.sh / install-local.{ps1,sh}. All four reverted: no skill staging from the release artifact, no agent-symlink loops. Post-install hint now points at the verb: ``` Agent skill pack (optional): cua-driver skills install ``` ## CD workflow - New step in the release job: package `Skills/cua-driver-rs/` into a single platform-agnostic `cua-driver-rs-v<v>-skills.tar.gz` asset and upload alongside the binary tarballs. - Reverted: the per-platform tarball changes (skills inside the macOS .app bundle, alongside the Linux/Windows binaries). The verb's dedicated asset is the only source. ## Module - New: `crates/cua-driver/src/skills.rs` (~390 LOC). HTTP via `ureq` (already a dep), tarball via `tar` + `flate2` (new deps). - `cli.rs`: new `Command::Skills { subcommand, flags }` variant + parsing + telemetry mapping (`cua_driver_skills_<sub>`). - `main.rs`: dispatch in both the macOS and other-OS branches. - Help text updated in cli.rs to document the verb. ## Telemetry `cua_driver_skills_install` / `_update` / `_uninstall` / `_status` / `_path` events, same shape as autostart's per-subcommand split. Respects the opt-out flag. ## Test plan - [x] Code review / structure - [ ] cua-driver-rs release with the skills.tar.gz asset - [ ] `cua-driver skills install` on the Win11 VM: fetches the tarball, places at `%USERPROFILE%\.cua-driver-rs\skills\cua-driver-rs`, junctions into `%USERPROFILE%\.claude\skills\cua-driver-rs` - [ ] `cua-driver skills status` reports correctly - [ ] `cua-driver skills uninstall --all` cleans up - [ ] macOS `ln -s` symlink path Follow-up issues for future work: - `cua-driver doctor` reports skill install state - `cua-driver skills install --local` flag pointing at install-local's staged copy
e1378eb to
ae3a14d
Compare
…rm banners - README.md: fix stale `Skills/cua-driver` paths → `Skills/cua-driver-rs`. Split Prerequisites into macOS / Windows / Linux sections (the previous flat list was macOS-only despite the cross-platform claim in the intro). Update install + invocation snippets (`/cua-driver` → `/cua-driver-rs`). Replace yabai/SLEventPostToPid macOS-specific jargon in "What the skill covers" with a per-platform breakdown. - WEB_APPS.md: platform banner at top — doc is macOS-only; point Windows readers at WINDOWS.md's "Web apps on Windows" section and Linux at LINUX.md. - RECORDING.md: platform banner — recording is macOS-only today; documents the Windows "not yet supported" message + Linux unsupported status. - TESTS.md: platform banner — prompts reference NSWorkspace / cmd / Finder / Numbers; explicitly mark macOS-only and point Windows / Linux readers at their respective triage sections. - LINUX.md: expand the X11 vs Windows-SendInput comparison to explain why focus-stealing matters here (Windows avoids it via PostMessage; Linux has no equivalent per-window-message channel). Net effect: a reader landing on any platform-flavoured doc can immediately tell whether they're on the right page; all install / copy / invoke snippets in README work as written; no stale `cua-driver` (Swift) path references remain in the cua-driver-rs Skills tree.
1 participant
Summary
Brings the Claude Code skill bundle from
libs/cua-driver/Skills/cua-driver/(macOS) intolibs/cua-driver-rs/Skills/cua-driver-rs/and adds platform-specific carve-outs for the cross-platform Rust port.This is PR A of a two-part split discussed in #1551:
WINDOWS.md+LINUX.mdstub + banner the macOS-skewedSKILL.mdso Windows / Linux agents can find the right doc.SKILL.mdinto a shared core +MACOS.mdadjunct, and wireinstall.ps1/install.shto deploy theSkills/dir at install time.PR A lets Windows agents load a useful skill today without touching the macOS workflow.
What's new
WINDOWS.md(686 lines, new) — Windows-specific skill covering:Start-Process(defaults toSW_SHOWNORMAL),SetForegroundWindow,SwitchToThisWindow,BringWindowToTop,cmd /c start,explorer.exe shell:AppsFolder\…,AttachThreadInputtricks, rawSendInput, ChromiumCtrl+L/Ctrl+T/Ctrl+1..9, Win+key shell shortcuts.urls-via-launch_app,hotkey({pid, keys:["alt","f4"]})for quit, etc.)."and spaces).IApplicationActivationManagerall return empty / time out in Session 0. The daemon must run via the autostart Scheduled Task (LogonType=Interactive), not via SSH-into-Windows.element_indexmode = UIAInvoke();(x,y)mode = layered UIA hit-test in target HWND subtree →PostMessage(WM_LBUTTONDOWN/UP)fallback. Right-click andcount > 1skip UIA Invoke per design. References the mechanism PR fix(windows-click): hit-test inside target HWND's UIA subtree for vision (x,y) #1551 ships.ApplicationFrameHost.exeouter hosting + inner UWP process, Win11 Calc / Notepad / Settings AUMIDs, whyStart-Process notepadgives you a 7 KB stub that exits.launch_app({urls}), forbidden browser shortcuts table, tabs-vs-windows pattern, WebView2 in non-browser hosts.0x80070578, the "Posted click to pid N" success message that didn't actually click on UWP, browser tab-switching leak, AUMID resolution misses, cold-launch HWND race.cua-driver doctorandautostart status.LINUX.md(84 lines, new) — BETA-status placeholder. Documents what works today (read-only inspection mostly), what doesn't (no FocusRestoreGuard equivalent, Wayland gated by portals, no recording), and lists the platform-specific forbidden vectors (wmctrl -a,xdotool windowactivate, etc.).SKILL.md— banner added at the top pointing Windows / Linux readers at the right carve-out file.name:frontmatter updated fromcua-driver→cua-driver-rs. Body unchanged from the macOS source.README.md— header + Files section updated to reflect cross-platform structure. TheWEB_APPS.mdnote now flags that Windows web-apps content lives inWINDOWS.mdinstead.WEB_APPS.md/RECORDING.md/TESTS.md— copied verbatim from the macOS skill. WEB_APPS.md stays macOS-only (Windows version embedded in WINDOWS.md).Test plan
WINDOWS.mdagainst PR fix(windows-click): hit-test inside target HWND's UIA subtree for vision (x,y) #1551's click chain — every claim about the layered UIA + PostMessage path matches the implementationWINDOWS.mdAUMID list againstGet-StartAppsoutput on the Win11 VMwc -lreports 2657 total lines across the skill dir (was 1843; +814 from WINDOWS.md / LINUX.md / README updates)SKILL.mdinto shared core +MACOS.md, wire install scriptsNotes
SKILL.mdbody is still macOS-skewed — that's intentional for this PR. Refactoring into a shared core is risky for the existing macOS agent workflow; doing it as a separate PR lets us validate the carve-out structure on Windows first.🤖 Generated with Claude Code
Summary by CodeRabbit
cua-driver-rsskill, covering installation/setup, core usage patterns, platform-specific operational guidance (macOS/Windows/Linux), web app automation strategies, testing procedures with real-world examples, session recording/replay functionality, and troubleshooting support.