trycua · f-trycua · May 23, 2026 · May 23, 2026
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md
@@ -1692,6 +1692,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
@@ -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
@@ -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

@@ -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"

@@ -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

@@ -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