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-rs): single shared post-install-hints.txt for all 4 Rust installers (#1664)

Francesco Bonacci23a9c8a1b95a
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md
index faaad766f3..806a7bb80e 100644
--- a/libs/cua-driver-rs/PARITY.md
+++ b/libs/cua-driver-rs/PARITY.md
@@ -1706,6 +1706,48 @@ arrays.
---
+## Installer post-install hints
+
+Not an MCP tool — an installer-text contract. The hint text printed at
+the end of every cua-driver-rs install (Try-it / agent skill pack / MCP
+setup per client / docs link) is sourced from a single shared file:
+
+- **Shared text**: `libs/cua-driver/scripts/post-install-hints.txt`
+ with `{{BINARY}}` placeholder.
+- **Renderers**: each of the 4 Rust installers reads the .txt, swaps
+ `{{BINARY}}` for the installed binary path, prints it, then appends
+ an OS-specific autostart hint inline:
+ - `libs/cua-driver/scripts/_install-rust.sh` — `curl` from
+ raw.githubusercontent.com (remote install path) + bash `sed`.
+ - `libs/cua-driver/scripts/install.ps1` — `Invoke-WebRequest` from
+ raw.githubusercontent.com + PowerShell `-replace`.
+ - `libs/cua-driver-rs/scripts/install-local.sh` — direct disk read
+ from `../cua-driver/scripts/post-install-hints.txt` + `sed`.
+ - `libs/cua-driver-rs/scripts/install-local.ps1` — direct disk read
+ from `..\cua-driver\scripts\post-install-hints.txt` + `-replace`.
+
+If the .txt is unreachable (network failure on remote installs, repo
+layout change on local), each installer falls back to a one-line
+essentials string so the user always gets enough to recover.
+
+**Why not a CLI subcommand**: an earlier draft of this work added
+`cua-driver post-install` to the Rust binary and had all 4 installers
+delegate via `& $installedBinary post-install`. Reverted — the
+chicken-and-egg risk (failed binary install = no hints either) made
+the .txt approach the safer choice. The .txt has no runtime
+dependency; even a totally broken binary install still prints hints.
+
+**Why OS-specific hints stay inline**: each script targets one OS
+(install.ps1 = Windows; install-local.sh on macOS vs Linux is the
+only branching case). The OS-specific block is 4-6 lines, naturally
+fits in the script that targets that OS, and is the only part that
+would need conditional rendering in a single-file design.
+
+**Status**: VERIFIED on macOS via `bash libs/cua-driver-rs/scripts/install-local.sh`
+end-to-end. Windows VM verification pending.
+
+---
+
## Focus-steal prevention
Cross-cutting infrastructure (not an MCP tool) used by `launch_app` and
diff --git a/libs/cua-driver-rs/scripts/install-local.ps1 b/libs/cua-driver-rs/scripts/install-local.ps1
index 66c05a63bd..a7c7640b31 100644
--- a/libs/cua-driver-rs/scripts/install-local.ps1
+++ b/libs/cua-driver-rs/scripts/install-local.ps1
@@ -232,14 +232,37 @@ if ($AutoStart) {
try {
Register-CuaDriverAutostart -InstalledBinary (Join-Path $VisibleBinDir $BinaryName)
Write-Host " Registered. cua-driver serve auto-starts at every interactive logon." -ForegroundColor Green
- Write-Host " Start now without re-logging: schtasks /Run /TN cua-driver-serve"
- Write-Host " Remove: schtasks /Delete /TN cua-driver-serve /F"
}
catch {
Write-Host " Failed to register: $($_.Exception.Message)" -ForegroundColor Red
}
+}
+
+# Unified post-install hints come from a single shared text file so the
+# 4 Rust installers (this script + install-local.sh + install.ps1 +
+# _install-rust.sh) never drift. The .txt holds the OS-agnostic bulk
+# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}}
+# placeholders; OS-specific bits stay inline below.
+$installedBinary = Join-Path $VisibleBinDir $BinaryName
+$HintsTxt = Join-Path $RepoRoot "..\cua-driver\scripts\post-install-hints.txt"
+if (Test-Path -LiteralPath $HintsTxt) {
+ $hintsRaw = Get-Content -Raw -LiteralPath $HintsTxt
+ Write-Host ($hintsRaw -replace '\{\{BINARY\}\}', $installedBinary)
} else {
- Write-Host "Auto-start (optional): re-run with -AutoStart to register a logon Scheduled Task,"
- Write-Host " or use 'schtasks /Run /TN cua-driver-serve' if you registered it previously."
+ # Repo layout changed or .txt missing — fall back to one-line
+ # essentials so users still know what to do next.
+ Write-Host "Next steps: $installedBinary --version | $installedBinary mcp-config | $installedBinary skills install"
+ Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+}
+
+# Windows-specific autostart hint (kept inline; per-shell natural location).
+if (-not $AutoStart) {
+ Write-Host ""
+ Write-Host "Auto-start at logon (Windows-native equivalent of macOS LaunchAgent):" -ForegroundColor Cyan
+ Write-Host " cua-driver autostart enable (register Scheduled Task at RunLevel=Highest)" -ForegroundColor Cyan
+ Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan
+ Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan
+ Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan
+ Write-Host " Or re-run install-local.ps1 with -AutoStart for the same result." -ForegroundColor Cyan
+ Write-Host ""
}
-Write-Host ""
diff --git a/libs/cua-driver-rs/scripts/install-local.sh b/libs/cua-driver-rs/scripts/install-local.sh
index 9432eff6f5..37fe279dd5 100755
--- a/libs/cua-driver-rs/scripts/install-local.sh
+++ b/libs/cua-driver-rs/scripts/install-local.sh
@@ -234,12 +234,25 @@ fi
echo "${BOLD}${GREEN}Installed.${NORMAL}"
echo " ${BOLD}$INSTALLED_BIN${NORMAL}"
echo ""
-echo "Verify:"
-echo " cua-driver --version"
-echo " cua-driver doctor"
-echo ""
+# Unified post-install hints come from a single shared text file so the
+# 4 Rust installers (this script + install-local.ps1 + _install-rust.sh +
+# install.ps1) never drift. The .txt holds the OS-agnostic bulk
+# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}}
+# placeholders; OS-specific bits stay inline below.
+HINTS_TXT="$REPO_ROOT/../cua-driver/scripts/post-install-hints.txt"
+if [ -f "$HINTS_TXT" ]; then
+ sed "s|{{BINARY}}|$INSTALLED_BIN|g" "$HINTS_TXT"
+else
+ # Repo layout changed or running from an unexpected location — fall
+ # back to one-line essentials so users still know what to do next.
+ echo "Next steps: $INSTALLED_BIN --version | $INSTALLED_BIN mcp-config | $INSTALLED_BIN skills install"
+ echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+fi
+
+# OS-specific autostart hint (kept inline; per-shell natural location).
if [ "$INSTALL_AUTOSTART" != true ]; then
+ echo ""
if [ "$OS" = "Darwin" ]; then
echo "Auto-start (optional): re-run with --autostart to register a LaunchAgent."
else
diff --git a/libs/cua-driver/scripts/_install-rust.sh b/libs/cua-driver/scripts/_install-rust.sh
index e5d9ef4e09..830287a01f 100644
--- a/libs/cua-driver/scripts/_install-rust.sh
+++ b/libs/cua-driver/scripts/_install-rust.sh
@@ -666,16 +666,38 @@ if [[ "${REPLACED_SWIFT:-0}" == "1" ]]; then
echo ""
fi
-echo "Try it:"
-echo " $BIN_LINK list-tools"
-echo " $BIN_LINK list_apps"
-echo ""
-echo "Agent skill pack (optional):"
-echo " $BIN_LINK skills install # fetch + link the cua-driver-rs skill pack"
-echo " # into Claude Code / Codex / OpenClaw / OpenCode."
-echo " # The install never touches your agent dirs."
-echo ""
-echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+# Unified post-install hints come from a single shared text file so the
+# 4 Rust installers (this script + install.ps1 + install-local.sh +
+# install-local.ps1) never drift. The .txt holds the OS-agnostic bulk
+# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}}
+# placeholders; OS-specific bits (autostart / TCC) stay inline below
+# in each installer where they're per-shell natural.
+HINTS_URL="https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/post-install-hints.txt"
+HINTS_TXT="$TMP_DIR/post-install-hints.txt"
+if curl -fsSL "$HINTS_URL" -o "$HINTS_TXT" 2>/dev/null && [ -s "$HINTS_TXT" ]; then
+ sed "s|{{BINARY}}|$BIN_LINK|g" "$HINTS_TXT"
+else
+ # Network fetch failed — print a one-line essentials fallback so the
+ # user always gets enough to recover, even if hint-text fetching is
+ # blocked. Skip everything else.
+ echo "Next steps: $BIN_LINK --version | $BIN_LINK mcp-config | $BIN_LINK skills install"
+ echo "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+fi
+
+case "$(uname -s)" in
+ Darwin)
+ echo ""
+ echo "macOS TCC: grant Accessibility + Screen Recording on first run:"
+ echo " open -n -g -a CuaDriver --args serve"
+ echo " $BIN_LINK check_permissions"
+ ;;
+ Linux)
+ echo ""
+ echo "Auto-start at logon (optional):"
+ echo " Re-run the local installer with --autostart to register a systemd user unit."
+ ;;
+esac
+
echo ""
echo "⚠️ BETA: cua-driver-rs is a cross-platform Rust port of the Swift"
echo " cua-driver. Windows and Linux support is feature-complete; macOS"
diff --git a/libs/cua-driver/scripts/install.ps1 b/libs/cua-driver/scripts/install.ps1
index 1b5136a297..1b8415788e 100644
--- a/libs/cua-driver/scripts/install.ps1
+++ b/libs/cua-driver/scripts/install.ps1
@@ -1137,10 +1137,6 @@ function Write-ManualPathInstructions([string]$dir) {
Write-Host ""
Write-Host "cua-driver-rs $version installed."
Write-Host ""
-Write-Host "Try it:"
-Write-Host " $installedBinary --version"
-Write-Host ""
-
$onPath = Test-OnUserPath $VisibleBinDir
if ($onPath) {
Write-Host "$VisibleBinDir is on your user PATH -- cua-driver should resolve in any new shell."
@@ -1170,12 +1166,6 @@ if ($AutoStart) {
try {
Register-CuaDriverAutostart -InstalledBinary $installedBinary
Write-Host " cua-driver serve will auto-start at every interactive logon (RunLevel=Highest)." -ForegroundColor Green
- Write-Host ' In a new PowerShell window, manage with:'
- Write-Host ' cua-driver autostart kick (run now without re-logging)'
- Write-Host ' cua-driver autostart status (inspect the task)'
- Write-Host ' cua-driver autostart disable (remove)'
- Write-Host " In THIS shell, use the full path: $installedBinary"
- Write-Host ""
}
catch {
Write-Host " Failed: $($_.Exception.Message)" -ForegroundColor Red
@@ -1184,29 +1174,32 @@ if ($AutoStart) {
Write-Host ""
}
}
-else {
- Write-Host "" -ForegroundColor Cyan
- Write-Host "Auto-start at logon (Windows equivalent of macOS LaunchAgent):" -ForegroundColor Cyan
- Write-Host " Run cua-driver serve automatically every time you sign in." -ForegroundColor Cyan
- Write-Host "" -ForegroundColor Cyan
- Write-Host " In a new PowerShell window (will prompt for admin once to register):" -ForegroundColor Cyan
- Write-Host " cua-driver autostart enable (register the task at RunLevel=Highest)" -ForegroundColor Cyan
- Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan
- Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan
- Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan
- Write-Host "" -ForegroundColor Cyan
- Write-Host " In THIS shell, prefix with the full Binary path:" -ForegroundColor Cyan
- Write-Host " $installedBinary" -ForegroundColor Cyan
- Write-Host "" -ForegroundColor Cyan
- Write-Host " Or re-run this installer with -AutoStart for the same result." -ForegroundColor Cyan
- Write-Host "" -ForegroundColor Cyan
- Write-Host " Without auto-start, you'll need to run 'cua-driver serve' manually." -ForegroundColor Cyan
- Write-Host " Auto-start spawns the daemon at logon at RunLevel=Highest, which is" -ForegroundColor Cyan
- Write-Host " needed for some elevated operations (registry, services, ACLs)." -ForegroundColor Cyan
-}
+# Unified post-install hints come from a single shared text file so the
+# 4 Rust installers (this script + _install-rust.sh + install-local.ps1 +
+# install-local.sh) never drift. The .txt holds the OS-agnostic bulk
+# (Try-it / skill pack / MCP setup / docs link) with {{BINARY}}
+# placeholders; OS-specific bits (autostart) stay inline below.
+$HintsUrl = "https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/post-install-hints.txt"
+try {
+ $hintsRaw = (Invoke-WebRequest -Uri $HintsUrl -UseBasicParsing -TimeoutSec 10).Content
+ Write-Host ($hintsRaw -replace '\{\{BINARY\}\}', $installedBinary)
+}
+catch {
+ # Network fetch failed — print one-line essentials so users always
+ # get enough to recover.
+ Write-Host "Next steps: $installedBinary --version | $installedBinary mcp-config | $installedBinary skills install"
+ Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+}
-Write-Host "Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs"
+# Windows-specific autostart hint (kept inline; OS-natural location).
+Write-Host ""
+Write-Host "Auto-start at logon (Windows-native equivalent of macOS LaunchAgent):" -ForegroundColor Cyan
+Write-Host " cua-driver autostart enable (Scheduled Task at RunLevel=Highest)" -ForegroundColor Cyan
+Write-Host " cua-driver autostart kick (start now without re-logging)" -ForegroundColor Cyan
+Write-Host " cua-driver autostart status (inspect)" -ForegroundColor Cyan
+Write-Host " cua-driver autostart disable (remove)" -ForegroundColor Cyan
+Write-Host " Or re-run this installer with -AutoStart for the same result." -ForegroundColor Cyan
Write-Host ""
Write-Host "WARNING -- BETA: cua-driver-rs is a cross-platform Rust port of the Swift" -ForegroundColor Yellow
Write-Host " cua-driver. Windows and Linux support is feature-complete; macOS" -ForegroundColor Yellow
diff --git a/libs/cua-driver/scripts/post-install-hints.txt b/libs/cua-driver/scripts/post-install-hints.txt
new file mode 100644
index 0000000000..ee9ce1ac99
--- /dev/null
+++ b/libs/cua-driver/scripts/post-install-hints.txt
@@ -0,0 +1,51 @@
+
+Next steps:
+
+ 1. Try it:
+ {{BINARY}} --version
+ {{BINARY}} list-tools
+
+ 2. Agent skill pack (optional):
+ {{BINARY}} skills install # fetch + link the cua-driver-rs skill pack
+ # into Claude Code / Codex / OpenClaw / OpenCode.
+ # The install never touches your agent dirs.
+
+ 3. As an MCP server — run the one matching your client. Each is also
+ available via '{{BINARY}} mcp-config --client <name>':
+
+ • Claude Code:
+ claude mcp add --transport stdio cua-driver -- {{BINARY}} mcp
+
+ Claude Code computer-use compatibility mode:
+ claude mcp add --transport stdio cua-computer-use -- {{BINARY}} mcp --claude-code-computer-use-compat
+ Use this when you want Claude Code's vision/computer-use-style flow
+ to ground on CuaDriver window screenshots. It keeps the normal
+ CuaDriver tools and changes only the screenshot tool.
+
+ • Codex (OpenAI):
+ codex mcp add cua-driver -- {{BINARY}} mcp
+
+ • OpenClaw:
+ {{BINARY}} mcp-config --client openclaw
+
+ • GitHub Copilot CLI (paste into ~/.copilot/mcp-config.json):
+ {
+ "mcpServers": {
+ "cua-driver": {
+ "type": "local",
+ "command": "{{BINARY}}",
+ "args": ["mcp"],
+ "tools": ["*"]
+ }
+ }
+ }
+
+ • Cursor / OpenCode / Hermes (no add CLI — paste config):
+ {{BINARY}} mcp-config --client cursor # JSON for ~/.cursor/mcp.json
+ {{BINARY}} mcp-config --client opencode # JSON for opencode.json
+ {{BINARY}} mcp-config --client hermes # YAML for ~/.hermes/config.yaml
+
+ For other clients accepting the generic mcpServers shape:
+ {{BINARY}} mcp-config
+
+Docs: https://github.com/trycua/cua/tree/main/libs/cua-driver-rs