trycua · ddupont808 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
@@ -19,12 +19,18 @@
   },
   "identityOverrides": {
     "ddupont@mit.edu": "ddupont808",
+    "egnichtel@crosscode.com": "ngnichtel",
     "f@trycua.com": "f-trycua",
+    "fbonacci@fbonacci-xfce-vm.b40fumexvs1ujlod2ppcyfh5qa.bx.internal.cloudapp.net": "f-trycua",
     "i@jyunko.cn": "HsiangNianian",
     "klymenko@adobe.com": "pavelklymenko",
     "m.fuechtenkoetter@posteo.de": "ai-ag2026",
     "manfred@ubuntu26.04-vm": "ai-ag2026",
+    "marko.civonafets@gmail.com": "civonafets",
+    "me@madhavajay.com": "madhavajay",
     "robert@trycua.com": "enchanted-koala",
+    "rsyuzyov@gmail.com": "rsyuzyov",
+    "rwendt1337@gmail.com": "r33drichards",
     "sarinajin.li@gmail.com": "sarinali",
     "zane.chee.2023@scis.smu.edu.sg": "injaneity",
     "zongxin_yang@hms.harvard.edu": "z-x-yang"

@@ -12,7 +12,7 @@ description: Reference for every MCP tool Cua Driver exposes
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-`cua-driver` exposes 49 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
+`cua-driver` exposes 51 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
 
 Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](/reference/cua-driver/cli-reference) for CLI-specific options like `--socket` and `--screenshot-out-file`.
 
@@ -902,6 +902,26 @@ Perform hover, right-click, double-click, scroll, or drag in an exactly-bound br
 {"action":"hover","session":"example","tab_id":"example","target_id":"example"}
 ```
 
+### `start_demonstration`
+
+Call only after the user explicitly asks to record a human demonstration. Start observing human input on one foreground Windows window. A red border is shown before capture starts. The border hides and input is ignored when the target loses foreground or rendering stops. Typed input content is never retained, but screenshots can contain text visible in the target window. Call stop_demonstration when the human finishes.
+
+**Arguments:**
+
+- `output_dir` (string, optional): New or empty output directory. Defaults to a unique directory under the system temporary directory.
+- `pid` (integer, required): Process id returned by list_windows.
+- `window_id` (integer, required): Window id returned by list_windows.
+
+```json
+{"pid":844,"window_id":10725}
+```
+
+### `stop_demonstration`
+
+Stop human input capture, remove the recording border, and write the trajectory and summary artifacts. Calling this without an active demonstration is a no-op.
+
+**Arguments:** none.
+
 ### `escalate_session`
 
 Unlock the desktop phase of an auto capture-scope session after the window action ladder has been exhausted and verified. This is a one-way transition for the live session and records a bounded reason.

@@ -14,6 +14,7 @@ members = [
     "crates/cursor-overlay",
     "crates/cursor-theme-cli",
     "crates/pip-preview",
+    "crates/input-capture",
 ]
 
 [workspace.package]

@@ -0,0 +1,99 @@
+# Demonstrations → skills
+
+> A demonstration-to-skill workflow. Record a human performing a task on a
+> window, then author a reusable `SKILL.md` from the resulting trajectory.
+> Generalization happens
+> in natural language — the skill describes *intent*, not pixel coordinates, so
+> it replays against a live screen rather than a brittle coordinate script.
+>
+> Recording how demonstration mode works + its security model lives in
+> `RECORDING.md`. This file is about turning a finished recording into a skill.
+
+## 1. Finish the demonstration
+
+Call `stop_demonstration`. It writes, next to the `turn-*/` folders:
+
+- **`TRAJECTORY.md`** — readable action prose; screenshots referenced by
+  **relative path**, only a few key frames embedded inline. Read THIS, not the
+  raw `action.json` tree — it will not blow up your context with base64.
+- **`SUMMARY.json`** — action count, duration, completeness, dropped-event and
+  screenshot-failure counts, and the action histogram.
+- **`DEMONSTRATION.json`** — schema and driver versions, target identity,
+  timestamps, stop reason, and capture completeness.
+
+## 2. Read the trajectory and identify the task
+
+Read `TRAJECTORY.md`. Open at most one or two of the linked
+`turn-*/screenshot.png` / `click.png` frames — only when an action's intent is
+unclear from the prose. Determine:
+
+- **What goal** the demonstration accomplishes (a sentence).
+- **The inputs** that varied or would vary across runs (names, dates, file
+  paths, search terms). These become `{placeholders}`.
+- **The meaningful steps** — collapse incidental turns (stray clicks, scrolls to
+  bring something into view, redacted typing that was just navigation) into
+  intent. Several low-level turns often map to one semantic step.
+
+## 3. Author SKILL.md (Open Agent Skills Standard)
+
+Write a single `SKILL.md` in the Open Agent Skills Standard:
+
+```markdown
+---
+name: kebab-case-name
+description: Use when <trigger>. Do NOT use when <anti-trigger>.
+---
+
+# <name>
+
+<one-line overview of what the task accomplishes>
+
+## Inputs
+- `{placeholder_one}` — what it is
+- `{placeholder_two}` — what it is
+
+## Steps
+1. Open <app/URL>
+2. Click the **Create New Report** button
+3. Enter the title as `{month}-{team}-expenses`
+4. <...>
+
+## Verification
+- <how to confirm success — what on screen proves the task completed>
+- <brief recovery note if a step doesn't land>
+```
+
+### Rules (what makes a skill good, not just correct)
+
+- **Frontmatter is two keys only**: `name` and `description`. The `description`
+  is a routing signal — front-load "Use when…"/"Do NOT use when…", not a
+  summary. All "when to use" info goes here, not in the body.
+- **Steps are semantic, never coordinates.** Write "Click the **Save** button",
+  not "click at (412, 880)". Recorded pixel coordinates are in the trajectory
+  for reference, but a coordinate-replay skill breaks on any layout change.
+  Refer to elements by visible name/role.
+- **Generalize literal text into `{placeholders}`.** Default capture records
+  only `text entered (redacted)` — never invent the literal value; represent it
+  as an input under `## Inputs`.
+- **Never invent or hardcode secrets.** Text input events are always redacted,
+  but screenshots can contain visible content. Review them before sharing and
+  make varying or sensitive values explicit inputs.
+- **Keep it minimal.** One screen of steps beats a transcript. Drop turns that
+  were just navigation.
+- **Always add a Verification section.** A skill the agent can't self-check is a
+  skill that fails silently.
+
+## 4. Sanity check
+
+- Could a fresh agent follow these steps on a slightly different screen? If a
+  step only makes sense at one resolution/position, re-write it semantically.
+- Are all varying values `{placeholders}` listed under `## Inputs`?
+- Does `description` make clear when NOT to trigger?
+
+## Where skills go
+
+cua-driver itself does not pick a skills directory for you — write the
+`SKILL.md` wherever your harness loads skills from (e.g. Claude Code
+`~/.claude/skills/<name>/`). The recording's
+`output_dir` is a fine staging spot; copy the finished skill into your harness's
+skills directory.
@@ -139,3 +139,35 @@ across builds) rather than a re-driving script.
 If recording is still enabled while replay runs, the replay is
 itself recorded into the current output directory — that's the
 intended regression-diff workflow.
+
+## Human demonstrations
+
+> **Windows only.** Human demonstrations are separate from ordinary tool-call
+> recording and are not automatically replayable.
+
+Call `start_demonstration` with the `pid` and `window_id` returned by
+`list_windows`. Call `stop_demonstration` when the task is complete. Stop writes
+`TRAJECTORY.md`, `SUMMARY.json`, and `DEMONSTRATION.json` next to the captured
+`turn-NNNNN/` folders. The summary and manifest mark the capture incomplete when
+hook events were dropped or screenshots were unavailable.
+
+The red border is a user notification. Cua-driver creates it before installing
+the input hook and drops input if border rendering stops. As a user-space
+overlay, it cannot prove that another window or a secure desktop has not
+obscured it.
+
+Capture has these limits:
+
+- events are accepted only while the selected top-level window is foreground;
+- the supplied window must belong to the supplied process;
+- cua-driver-injected events are ignored;
+- text input events record only `text entered (redacted)` and never retain
+  literal text or its length;
+- screenshots can still contain text and other content visible in the target
+  window, so review artifacts before sharing them;
+- the hook and border stop on `stop_demonstration` or when the owning MCP
+  session ends.
+
+Use the bundled **`DEMONSTRATION.md`** guide to turn `TRAJECTORY.md` into a
+skill. Skill authoring remains in the host agent; cua-driver makes no model API
+request.
@@ -59,7 +59,9 @@ Cross-cutting topics also have their own files:
 - `BROWSER.md` — exact native-window binding, explicit browser preparation,
   typed Chromium/Electron page tools, input trust classes, and native
   fallbacks for browser chrome and unsupported engines.
-- `RECORDING.md` — session recording + `replay_trajectory`.
+- `RECORDING.md` — session recording, human demonstrations, and
+  `replay_trajectory`.
+- `DEMONSTRATION.md` — turning a human demonstration into a reusable skill.
 
 Use whichever combination matches the host. When in doubt, run
 `cua-driver doctor` — it reports the platform and the right entry

@@ -36,6 +36,10 @@ base64 = { workspace = true }
 sha2 = "0.10"
 url = "2.5"
 
+# Window-scoped human input capture. The Windows backend is implemented;
+# other platforms return Unsupported.
+input-capture = { path = "../input-capture" }
+
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
 

@@ -833,7 +833,8 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {
         | "end_session"
         | "set_agent_cursor_enabled"
         | "set_agent_cursor_motion"
-        | "set_agent_cursor_theme" => RiskClass::R1,
+        | "set_agent_cursor_theme"
+        | "stop_demonstration" => RiskClass::R1,
 
         // Surfaces that can reveal or control sensitive local/authenticated
         // state. Active adapters still decide their exact resource scope at
@@ -847,6 +848,7 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {
         | "set_config"
         | "escalate_session"
         | "start_recording"
+        | "start_demonstration"
         | "get_browser_state"
         | "browser_prepare"
         | "browser_navigate"