[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F79Q9CRKA3ECK749EDRASH":3,"skill-same:01M7F79Q9CRKA3ECK749EDRASH":71},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M7F79Q9CRKA3ECK749EDRASH","agent-desktop",null,"Reliable computer use via native OS accessibility trees. Use when an AI agent needs to see and operate desktop applications (click buttons, fill forms, navigate menus, read UI state, toggle checkboxes, scroll, drag, type text, take screenshots, manage windows, use clipboard, manage notifications). Covers 59 command names (55 operational; four held-input names fail closed until daemon ownership exists) across observation, interaction, keyboard\u002Fmouse, app lifecycle, notifications (macOS), clipboard, wait, session lifecycle, and a `skills` command that bundles docs straight from the binary. Triggers on: \"click button\", \"fill form\", \"open app\", \"read UI\", \"computer use\", \"operate desktop\", \"accessibility tree\", \"snapshot app\", \"type into field\", \"navigate menu\", \"toggle checkbox\", \"take screenshot\", \"desktop automation\", \"agent-desktop\", or any desktop GUI interaction task. Supports the macOS Phase 1 adapter, with Windows and Linux planned against the same core contracts.","lza6\u002FArmor-piercing-system-prompts","lza6","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F128880206?v=4","01M7EB3K7WPX5T28EJ2NVHE6EG","Chinese-tingfeng","01M7EB3K97E1KQ16QWKJMFNGX8",11,"MIT","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: agent-desktop\nversion: 0.4.0\ntags: computer-use, desktop-automation, accessibility, ai-agent, gui-automation, cli\nrequirements:\n  - agent-desktop\ndescription: >\n  Reliable computer use via native OS accessibility trees.\n  Use when an AI agent needs to see and operate desktop applications\n  (click buttons, fill forms, navigate menus, read UI state, toggle checkboxes, scroll,\n  drag, type text, take screenshots, manage windows, use clipboard, manage notifications).\n  Covers 59 command names (55 operational; four held-input names fail closed until\n  daemon ownership exists) across observation, interaction, keyboard\u002Fmouse, app\n  lifecycle, notifications (macOS), clipboard, wait, session lifecycle, and a\n  `skills` command that bundles docs straight from the binary.\n  Triggers on: \"click button\", \"fill form\", \"open app\", \"read UI\", \"computer use\",\n  \"operate desktop\", \"accessibility tree\", \"snapshot app\", \"type into field\", \"navigate menu\",\n  \"toggle checkbox\", \"take screenshot\", \"desktop automation\", \"agent-desktop\", or any desktop GUI interaction task.\n  Supports the macOS Phase 1 adapter, with Windows and Linux planned against\n  the same core contracts.\n---\n\n# agent-desktop\n\nComputer-use tool that AI agents call to see and operate desktop applications via native OS accessibility trees.\n\n**Core principle:** agent-desktop is NOT an AI agent. It is a tool that AI agents invoke. It outputs structured JSON with ref-based element identifiers. The observation-action loop lives in the calling agent.\n\n## Installation\n\n```bash\nnpm install -g agent-desktop\n# or\nbun install -g --trust agent-desktop\n```\n\nRequires macOS 12+ with Accessibility permission granted to your terminal. Screen Recording permission is also required for screenshots.\n\n## Reference Files\n\nDetailed documentation is split into focused reference files. Read them as needed:\n\n| Reference | Contents |\n|-----------|----------|\n| `references\u002Fcommands-observation.md` | snapshot, find, get, is, screenshot, list-surfaces — all flags, output examples |\n| `references\u002Fcommands-interaction.md` | click, type, set-value, select, toggle, scroll, drag, keyboard, mouse — choosing the right command |\n| `references\u002Fcommands-system.md` | launch (including `--cdp` for Chromium web contents), close, windows, clipboard, wait, batch, session, status, permissions, version |\n| `references\u002Fworkflows.md` | 17 common patterns: forms, menus, dialogs, scroll-find, drag-drop, async wait, anti-patterns |\n| `references\u002Fmacos.md` | macOS permissions\u002FTCC, AX API internals, smart activation chain, surfaces, Notification Center, troubleshooting |\n\n## The Observe-Act Loop (Progressive Skeleton Traversal)\n\nWhen you know the target's role or exact name, use `find --role ... --name ... --exact` directly. Otherwise, use **progressive skeleton traversal** for dense or unfamiliar apps: a shallow overview followed by targeted drill-downs.\n\n```\n1. SKELETON → agent-desktop snapshot --skeleton --app \"App\" -i --compact\n   Parse the overview. Identify the region containing your target.\n   Regions show children_count (e.g., \"Sidebar\" with children_count: 42).\n   The nearest safely resolvable container has a ref for drill-down.\n   Keep the returned snapshot_id.\n\n2. DRILL    → agent-desktop snapshot --root @e3 --snapshot \u003Csnapshot_id> -i --compact\n   Expand the target region. Now you see its interactive elements.\n\n3. ACT      → agent-desktop click @e12 --snapshot \u003Csnapshot_id>  (or type, select, toggle...)\n\n4. VERIFY   → agent-desktop snapshot --root @e3 --snapshot \u003Csnapshot_id> -i --compact\n   Re-drill the same region to confirm the state change.\n   Scoped invalidation: only @e3's subtree refs are replaced.\n\n5. REPEAT   → Continue drilling other regions or acting as needed.\n```\n\n**When to skip skeleton and use full snapshot instead:**\n- Simple apps with few elements (Finder, Calculator, TextEdit)\n- You already know the exact element name — use `find` instead\n- Surface snapshots (menus, sheets, alerts) — these are already focused\n\n**When skeleton shines:**\n- Dense Electron apps (Slack, VS Code, Discord, Notion) that are **already running** — for one you are launching fresh, `launch --cdp` plus a CDP client (agent-browser preferred) reads the web contents faster than any skeleton walk (see principle 15)\n- Any app where full snapshot exceeds ~50 refs\n- Multi-region workflows (sidebar + main content + toolbar)\n\n## Ref System\n\n- Refs are assigned depth-first and emitted with their snapshot, for example `@s8f3k2p9:e1`, `@s8f3k2p9:e2`, `@s8f3k2p9:e3`. Legacy bare refs require an explicit `--snapshot`.\n- An element gets a ref when it is addressable for an action: an interactive role (button, textfield, checkbox, link, menuitem, tab, slider, combobox, treeitem, cell, radiobutton, switch, ...) **or** any element advertising an action — so `scrollarea` (Scroll) and `disclosure` (Expand\u002FCollapse) are ref-able and `scroll`\u002F`expand`\u002F`collapse` can target them\n- A `SetFocus`-only affordance does not earn a ref on its own\n- In skeleton mode, each truncated branch exposes the deepest safely resolvable drill target using stable text, native ID, or bounds evidence; the nearest resolvable ancestor is used when the boundary itself is anonymous\n- Static text and non-actionable groups\u002Fcontainers remain in tree for context but have no ref\n- Refs are deterministic within a snapshot but NOT stable across snapshots if UI changed\n- Snapshot output uses qualified refs that embed `snapshot_id` and need no separate `--snapshot`; a session-owned ref still requires the same `--session` or `AGENT_DESKTOP_SESSION` scope because lookup never crosses namespaces\n- `last_refmap.json` is only a latest-snapshot inspection artifact. The command path uses snapshot-scoped storage.\n- After any action that changes UI, re-drill the affected region or re-snapshot\n- **Scoped invalidation:** re-drilling a qualified root ref only replaces refs from that root's previous drill — refs from other regions and the skeleton itself are preserved\n- **Strict resolution:** stale refs return `STALE_REF`; duplicate plausible targets return `AMBIGUOUS_TARGET` instead of choosing arbitrarily.\n- **Actionability:** every ref-addressed action checks its applicable live visibility, stability, enabled, editability, policy, supported-action, and hit-test requirements under one bounded budget before a single dispatch. Pointer actions focus before their final geometry read, re-resolve moving endpoints, and return `TIMEOUT` with `details.kind: \"actionability_timeout\"` instead of sending input after the deadline.\n- **Headless vs headed:** ref actions are strictly headless by default: semantic accessibility APIs only, with no focus stealing, cursor movement, or synthesized keyboard input. In headed mode, core focuses the exact ref window before dispatch; pointer actions also require a verified target point, while the adapter owns OS delivery. On macOS, `click`, `right-click`, `type`, `clear`, and `scroll` are physical-first; double\u002Ftriple-click, hover, and drag are physical-only; expand\u002Fcollapse and other semantic actions remain semantic. Raw `--xy` input has no window identity and never steals focus. `press` is explicit physical keyboard input; held-input commands (`key-down`, `key-up`, `mouse-down`, `mouse-up`) are reserved and fail closed in the stateless CLI.\n- **Sessions and tracing:** run `session start` once per task to create a manifest with `trace: on` (default), then pass its returned ID with `--session` or `AGENT_DESKTOP_SESSION`. Use `session start --screenshots` when you need replay artifacts (`artifacts: full`): pre\u002Fpost-action PNGs and refmap copies under the session trace directory (sensitive — treat exports like screenshots). Commands in that explicit scope record JSONL automatically to per-process segments under `~\u002F.agent-desktop\u002Fsessions\u002F\u003Cid>\u002Ftrace\u002F\u003Cpid>-\u003CprocTs>.jsonl` — no `--trace` on every call. Read traces back with `trace show` (bounded JSON for agents) or `trace export` (single-file HTML for humans). A session owns both its trace and its latest-snapshot namespace. Snapshot lookup never searches another namespace. **`--session \u003Cid>` alone** (no manifest from `session start`) selects only the snapshot namespace — existing callers see no surprise trace files. **`--trace \u003Cpath>`** still overrides to one atomic file for CI or one-offs. Activation precedence is `--session` > `AGENT_DESKTOP_SESSION` > no session; `session start` does not activate later processes. Multi-agent shared sessions: the harness passes the same session ID to every subagent. For independent macOS cursors use `session start --cursor --multi-agent` and assign each subagent a stable `AGENT_DESKTOP_AGENT_ID` or global `--agent-id` (flag wins). Desktop UI actions then require the ID; observations, clipboard operations, and administration do not. Three distinct IDs produce three cursors, in both headless and headed mode. Drags reuse the cursor’s curved motion and show a live accent-colored trail while held, fading after release; the ripple setting controls the trail. Physical pointer commands also show their agent’s overlay; the interaction lease serializes access to the shared OS pointer. Each agent acts on qualified refs from its own snapshot — implicit latest is not a cross-agent guarantee. Optional `--agent-id \u003Cid> cursor-overlay enable` styling is saved for that agent’s next presentation; no registration is needed. Disable\u002Fend stops every session cursor. Run `status` to see `session_id` and `tracing`. Trace lines include `ts_ms`, monotonic per-process `seq`, and redacted sensitive fields (`text`, `value`, `expected`, `name`, `username`, `description`, `label`, `query`, `secret`, `token`, `password`, `title`, `url`, `help`, `placeholder` → `{ \"redacted\": true }`). `--trace-strict` fails on trace setup and pre-action writes; post-action success traces are best-effort.\n\n## JSON Output Contract\n\nEvery command returns a JSON envelope on stdout:\n\n**Success:** `{ \"version\": \"2.4\", \"ok\": true, \"command\": \"snapshot\", \"data\": { ... } }`\n**Error:** `{ \"version\": \"2.4\", \"ok\": false, \"command\": \"click\", \"error\": { \"code\": \"STALE_REF\", \"message\": \"...\", \"suggestion\": \"...\" } }`\n\nThe `error` object may also carry an optional `details` object (e.g. the actionability report on an actionability failure, candidate summaries on `AMBIGUOUS_TARGET`, or the last observed state on a `wait` `TIMEOUT`). Parse errors leniently — `details` and future fields are additive, so do not reject responses with unknown keys.\n\nAn error also carries `disposition`, and that object decides whether a retry is safe:\n\n| Field | Values |\n|-------|--------|\n| `disposition.delivery` | `not_delivered`, `delivery_uncertain`, `delivered_unverified`, `delivered_verified`, `unknown` |\n| `disposition.retry` | `safe`, `unsafe`, `unknown` |\n\n**Retry or substitute an action only when `disposition.retry` is `safe`, and follow `recovery.strategy` only in that same case.** Only `not_delivered` is `safe`. Every other delivery value is `unsafe`, because the action may already have landed — repeating it would click, type, or submit twice. On an `unsafe` result, read `details.post_state` and `details.postcondition_satisfied` to decide what actually happened, then act on the observed state instead of repeating the command. A failure after preparatory scrolling carries `details.preparatory_scroll` and never authorizes an automatic retry.\n\nAn actionability failure on a hit-test action (`click`, `double-click`, `right-click`, `triple-click`, `hover`, `drag`) can carry a `receives_events` check with `reason: \"occluded by \u003Crole>\"` plus a structured `occluder: { \"role\", \"name\", \"bounds\" }` — another element is on top of the target. Bring the target window\u002Felement to the front (or dismiss the occluder) rather than blind-retrying; see `references\u002Fcommands-interaction.md` for the full check list.\n\nExit codes: `0` success, `1` structured error, `2` argument error.\n\n### Error Codes\n\n| Code | Meaning | Recovery |\n|------|---------|----------|\n| `PERM_DENIED` | Accessibility or Screen Recording permission not granted | Grant the named permission in System Settings |\n| `ELEMENT_NOT_FOUND` | Ref cannot be resolved against the live UI | Re-run snapshot, use fresh ref |\n| `APP_NOT_FOUND` | App not running | Launch it first |\n| `ACTION_FAILED` | Action rejected or its observed result contradicted the request | Inspect `disposition.retry`, `details.post_state`, and `details.after_action`; do not repeat or substitute an action after uncertain or unverified delivery |\n| `ACTION_NOT_SUPPORTED` | Element can't do this | Use different command |\n| `STALE_REF` | Ref could not be re-identified in the live UI | Use the `snapshot_id` returned with this ref; if the UI changed or the target disappeared, re-run `snapshot` \u002F `snapshot --skeleton` to get fresh refs |\n| `AMBIGUOUS_TARGET` | Multiple elements matched the old ref identity | Re-run snapshot and choose a more specific ref |\n| `SNAPSHOT_NOT_FOUND` | Snapshot ID is missing or expired | Run `snapshot` again and use the returned ID |\n| `POLICY_DENIED` | A physical\u002Fheaded path was blocked | Use an explicit mouse\u002Ffocus\u002Fkeyboard command if physical interaction is intended |\n| `APP_UNRESPONSIVE` | A read-only AX liveness probe also failed after an uncertain mutation response | Inspect with a fresh snapshot and wait for the app to recover before deciding whether to retry |\n| `WINDOW_NOT_FOUND` | No matching window | Check app name, use list-windows |\n| `PLATFORM_NOT_SUPPORTED` | Adapter method not implemented on this platform | Use a supported platform adapter |\n| `TIMEOUT` | Wait or actionability condition not met | Inspect `error.details.kind`; increase the command budget only after checking the last report, and use `AGENT_DESKTOP_CHAIN_TIMEOUT_MS` only for `chain_deadline` |\n| `INVALID_ARGS` | Bad arguments | Check command syntax |\n| `NOTIFICATION_NOT_FOUND` | Notification index no longer exists | Re-run list-notifications |\n| `INTERNAL` | Unexpected platform\u002FOS failure (e.g. event synthesis failed) | Read `message`\u002F`suggestion` for cleanup state, then retry once; persistent failures indicate an environment problem |\n\n`TIMEOUT` errors carry a `details` object whose `kind` field selects the schema. `kind: \"wait_timeout\"` includes `predicate`, `timeout_ms`, and `last_observed` or `last_error`, plus `ref`\u002F`title`\u002F`text_chars` depending on the wait mode. `kind: \"chain_deadline\"` includes `value_before`, `value_at_timeout`, `target`, and `mutated` (increment waits) or `wanted_expanded`\u002F`observed_expanded` (disclosure waits). `mutated: true` — or an unknown `observed_expanded` state — means re-read the element before retrying; `mutated: false` means the state did not change and retrying directly is safe.\n\n`details.kind: \"post_action_verification\"` means execution was followed by a contradictory or failed state read. The original read error code is preserved, so even `STALE_REF` or `TIMEOUT` can follow delivery. Inspect `post_state`, `after_action`, and `disposition.retry` before any retry or alternative action. Missing evidence alone is reported as successful `delivered_unverified` with `details.verification_scope: \"unavailable\"`, not as proof that the change failed.\n\n## Command Quick Reference (59 names, 55 operational)\n\n### Observation\n```\nagent-desktop snapshot --skeleton --app \"App\" -i --compact  # Skeleton overview (preferred)\nagent-desktop snapshot --root @s8f3k2p9:e3 -i --compact              # Drill into region\nagent-desktop snapshot --app \"App\" -i                       # Full tree (simple apps)\nagent-desktop snapshot --app \"App\" --surface menu -i        # Surface snapshot\nagent-desktop screenshot --app \"App\" out.png                # PNG screenshot\nagent-desktop find --app \"App\" --role button                # Search elements\nagent-desktop find --root @s8f3k2p9:e3 --role button        # Search one region only\nagent-desktop find --app \"App\" --surface menubar --name \"Save\" --first  # Search a menu\nagent-desktop get @e1 --snapshot \u003Csnapshot_id> --property text       # Read element property\nagent-desktop is @e1 --snapshot \u003Csnapshot_id> --property enabled     # Check element state\nagent-desktop list-surfaces --app \"App\"                     # Available surfaces\n```\n\nFor a visual demo on macOS, add `--debug --screenshot \u002Ftmp\u002Fvisual.html` to `snapshot` or `click`. The local HTML viewer has ref highlights and collapsible role groups with checkbox filters. Choose a new file; see [Visual debug](references\u002Fcommands-observation.md#visual-debug).\n\n### Interaction\n```\nagent-desktop click @e5 --snapshot \u003Csnapshot_id> # Headless semantic click\nagent-desktop --headed double-click @s8f3k2p9:e3 # physical double-click\nagent-desktop --headed triple-click @s8f3k2p9:e2 # physical triple-click\nagent-desktop right-click @s8f3k2p9:e5          # Right-click; inspect the resulting menu\u002Feffect separately\nagent-desktop type @e2 --snapshot \u003Csnapshot_id> \"hello\"  # Headless AX text insertion when supported\nagent-desktop set-value @s8f3k2p9:e2 \"new value\"         # Set value directly\nagent-desktop clear @s8f3k2p9:e2                         # Clear element value\nagent-desktop focus @s8f3k2p9:e2                         # Set keyboard focus\nagent-desktop select @s8f3k2p9:e4 \"Option B\"             # Select dropdown\u002Flist option\nagent-desktop toggle @s8f3k2p9:e6                        # Toggle checkbox\u002Fswitch\nagent-desktop check @s8f3k2p9:e6                         # Idempotent check\nagent-desktop uncheck @s8f3k2p9:e6                       # Idempotent uncheck\nagent-desktop expand @s8f3k2p9:e7                        # Expand disclosure\nagent-desktop collapse @s8f3k2p9:e7                      # Collapse disclosure\nagent-desktop scroll @s8f3k2p9:e1 --direction down       # Scroll element\nagent-desktop scroll-to @s8f3k2p9:e8                     # Scroll into view\n```\n\n### Keyboard & Mouse\n```\nagent-desktop press cmd+c                       # Key combo\nagent-desktop press return --app \"App\"          # Targeted key press\nagent-desktop --headed hover @s8f3k2p9:e5       # Explicit cursor movement\nagent-desktop --headed hover --xy 500,300       # Cursor to coordinates\nagent-desktop --headed drag --from @s8f3k2p9:e1 --to @s8f3k2p9:e5 # Drag between elements\nagent-desktop --headed mouse-click --xy 500,300 # Click at coordinates\nagent-desktop --headed mouse-move --xy 100,200  # Move cursor\n```\n\n`key-down`, `key-up`, `mouse-down`, and `mouse-up` return `ACTION_NOT_SUPPORTED` until a stateful daemon can own held-input lifetime. Use `press`, `mouse-click`, or `drag` instead.\n\n### App & Window\n```\nagent-desktop launch \"System Settings\"          # Launch; returns once running\nagent-desktop launch \"TextEdit\" --activate       # Also bring it forward and wait for a window\nagent-desktop launch \"Obsidian\" --cdp            # Fresh launch + verified Chrome DevTools Protocol port for web contents\nagent-desktop close-app \"TextEdit\"              # Quit gracefully\nagent-desktop close-app \"TextEdit\" --force      # Force quit; SIGKILL if SIGTERM does not exit\nagent-desktop list-windows --app \"Finder\"       # List windows\nagent-desktop list-apps                         # List running GUI apps\nagent-desktop focus-window --app \"Finder\"       # Bring to front\nagent-desktop resize-window --app \"App\" --width 800 --height 600\nagent-desktop move-window --app \"App\" --x 0 --y 0\nagent-desktop minimize --app \"App\"\nagent-desktop maximize --app \"App\"\nagent-desktop restore --app \"App\"\n```\n\nUse `--window-id \u003Cid>` from `list-windows` instead of `--app` when an app has multiple windows.\n\n### Notifications\n```\nagent-desktop --headed list-notifications                # Open center if needed, then list\nagent-desktop --headed list-notifications --app \"Slack\"  # Filter by app\nagent-desktop --headed list-notifications --text \"deploy\" --limit 5  # Filter by text\nagent-desktop --headed dismiss-notification 1 --expected-app Slack --expected-title \"Deploy complete\"\nagent-desktop --headed dismiss-all-notifications         # Dismiss all\nagent-desktop --headed dismiss-all-notifications --app \"Slack\"  # Dismiss all from app\nagent-desktop --headed notification-action 1 \"Reply\" --expected-app Slack --expected-title \"Deploy complete\"\n```\n\nEvery notification mutation requires global `--headed`; single-notification\nmutations also require an app or title fingerprint from the same listing.\nHeadless listing works only while Notification Center is already open.\n\n### Clipboard\n```\nagent-desktop clipboard-get                     # Read clipboard\nagent-desktop clipboard-set \"text\"              # Write to clipboard\nagent-desktop clipboard-clear                   # Clear clipboard\n```\n\n### Wait\n```\nagent-desktop wait 1000                         # Pause 1 second\nagent-desktop wait --element @e5 --snapshot \u003Csnapshot_id> --timeout 5000 # Wait for element\nagent-desktop wait --element @s8f3k2p9:e5 --predicate actionable --timeout 5000 # Wait until actionable\nagent-desktop wait --element @s8f3k2p9:e5 --predicate value --value \"Done\" --timeout 5000 # Wait for value\nagent-desktop wait --window \"Title\"             # Wait for window\nagent-desktop wait --text \"Done\" --app \"App\"    # Wait for text\nagent-desktop wait --menu --app \"App\"           # Wait for menu surface\nagent-desktop wait --menu-closed --app \"App\"    # Wait for menu dismissal\nagent-desktop wait --notification --app \"App\"   # Wait for new notification\n```\n\n### System\n```\nagent-desktop session start [--name LABEL] [--screenshots] [--no-trace] [--cursor [--multi-agent]]  # Creates a session; pass the returned ID explicitly\nagent-desktop session end [id]                                      # Seal manifest\nagent-desktop session list                                          # List session manifests\nagent-desktop session gc [--older-than SECS] [--ended]              # Reclaim ended\u002Fstale sessions\nagent-desktop --session \u003Cid> cursor-overlay enable [--multi-agent] [--label TEXT] [--max-words N] [--fill HEX] [--rim HEX] [--accent HEX] [--size N] [--no-ripple] [--no-highlight]\nagent-desktop --session \u003Cid> --agent-id ID cursor-overlay enable [--label TEXT] [--max-words N] [--fill HEX] [--rim HEX] [--accent HEX] [--size N] [--no-ripple] [--no-highlight]\nexport AGENT_DESKTOP_SESSION=\u003Cid>\nagent-desktop cursor-overlay disable                                # Stop all cursors in the selected session\nagent-desktop trace show [--limit N] [--event PREFIX]               # Merge trace segments (default tail 500; 0 = all)\nagent-desktop trace export [--out path.html] [--limit N]            # Self-contained HTML viewer (default tail 5000)\nagent-desktop status                            # Health, session_id, tracing, artifacts, permissions\nagent-desktop permissions                       # Check permission\nagent-desktop permissions --request             # Request missing permissions in an isolated helper\nagent-desktop version                           # Version info (always JSON envelope)\nagent-desktop batch '[...]' --stop-on-error     # Batch uses the same typed command path as CLI\nagent-desktop skills                            # List bundled skill docs\nagent-desktop skills get desktop --full         # Load this skill + all references\n```\n\n## Key Principles for Agents\n\n1. **Find known targets; skeleton unknown structure.** If role or exact name is known, use targeted `find` first. Use `--skeleton -i --compact` when the region is unknown, then drill with `--root @ref`. For fresh Chromium launches, prefer `launch --cdp` plus a CDP client.\n2. **Use `-i --compact` flags.** Filters to interactive elements and collapses empty wrappers, minimizing tokens.\n3. **Refs are snapshot-scoped.** Keep `snapshot_id` for deterministic multi-step use; re-drill the affected region after any UI-changing action. Scoped invalidation keeps other refs intact.\n4. **Prefer refs over coordinates.** `click @s8f3k2p9:e5` > `agent-desktop --headed mouse-click --xy 500,300`.\n5. **Use `wait` for async UI.** After launch\u002Fdialog triggers, wait for expected state.\n6. **Check permissions first.** Run `permissions` on first use; screenshots also need Screen Recording.\n7. **Handle errors.** Branch on `error.code` only — `error.message` and `error.suggestion` text is informational and may change between versions.\n8. **Scope targeted searches.** Pair known names with role and `--exact`; use `--limit 2` before a mutation when uniqueness is not guaranteed. Narrow with `--root @ref` for one region or `--surface menubar` for a menu.\n9. **Use surfaces for overlays.** `snapshot --surface menu` for menus, `--surface sheet` for dialogs. Never `--skeleton` for surfaces — they're already focused. Reach one item inside an overlay with `find --surface`, not a full surface snapshot.\n10. **Read `data.surfaces` after acting.** An action that opens a sheet, menu, or alert reports it there. Target that overlay next instead of searching windows for what changed.\n11. **Batch for performance.** Multiple commands in one invocation.\n12. **Headless by default.** Ref actions use semantic AX paths and block silent focus stealing, cursor movement, keyboard synthesis, and pasteboard insertion. Use `--headed` only when exact-window focus or physical delivery is intended; raw coordinates never imply focus.\n13. **Start a session once per run.** `session start` creates the manifest; pass its returned ID through `AGENT_DESKTOP_SESSION` for the run or `--session \u003Cid>` for one command. It does not activate later processes implicitly.\n14. **Trace hard failures.** With an active trace-enabled session, segments are written automatically. Add `--trace \u002Ftmp\u002Fagent-desktop.jsonl` only when you need a single override file (CI, one-offs). Check `status` when unsure whether tracing is active.\n15. **Relocate state with `AGENT_DESKTOP_HOME`.** When set, the env value is the state root itself — sessions, refmaps, traces, and locks all live under it, for every subcommand. Default stays `~\u002F.agent-desktop`. The value must be an absolute path; a relative or empty value fails with `INVALID_ARGS` before any command runs. `status` reports the resolved root as `state_root`. Explicit output paths (`screenshot --out`, `--trace \u003Cpath>`) are never re-rooted.\n16. **Chromium-app strategy.** The accessibility path is the default, and the only option for already-running apps and for native surfaces (menus, dialogs, windows). `launch --cdp` plus a CDP client (agent-browser preferred; any CDP client works) is the opt-in fast path for a Chromium app's web contents, when a fresh launch is acceptable.\n","# agent-desktop\n\nComputer-use tool that AI agents call to see and operate desktop applications via native OS accessibility trees.\n\n**Core principle:** agent-desktop is NOT an AI agent. It is a tool that AI agents invoke. It outputs structured JSON with ref-based element identifiers. The observation-action loop lives in the calling agent.\n\n## Installation\n\n```bash\nnpm install -g agent-desktop\n# or\nbun install -g --trust agent-desktop\n```\n\nRequires macOS 12+ with Accessibility permission granted to your terminal. Screen Recording permission is also required for screenshots.\n\n## Reference Files\n\nDetailed documentation is split into focused reference files. Read them as needed:\n\n| Reference | Contents |\n|-----------|----------|\n| `references\u002Fcommands-observation.md` | snapshot, find, get, is, screenshot, list-surfaces — all flags, output examples |\n| `references\u002Fcommands-interaction.md` | click, type, set-value, select, toggle, scroll, drag, keyboard, mouse — choosing the right command |\n| `references\u002Fcommands-system.md` | launch (including `--cdp` for Chromium web contents), close, windows, clipboard, wait, batch, session, status, permissions, version |\n| `references\u002Fworkflows.md` | 17 common patterns: forms, menus, dialogs, scroll-find, drag-drop, async wait, anti-patterns |\n| `references\u002Fmacos.md` | macOS permissions\u002FTCC, AX API internals, smart activation chain, surfaces, Notification Center, troubleshooting |\n\n## The Observe-Act Loop (Progressive Skeleton Traversal)\n\nWhen you know the target's role or exact name, use `find --role ... --name ... --exact` directly. Otherwise, use **progressive skeleton traversal** for dense or unfamiliar apps: a shallow overview followed by targeted drill-downs.\n\n```\n1. SKELETON → agent-desktop snapshot --skeleton --app \"App\" -i --compact\n   Parse the overview. Identify the region containing your target.\n   Regions show children_count (e.g., \"Sidebar\" with children_count: 42).\n   The nearest safely resolvable container has a ref for drill-down.\n   Keep the returned snapshot_id.\n\n2. DRILL    → agent-desktop snapshot --root @e3 --snapshot \u003Csnapshot_id> -i --compact\n   Expand the target region. Now you see its interactive elements.\n\n3. ACT      → agent-desktop click @e12 --snapshot \u003Csnapshot_id>  (or type, select, toggle...)\n\n4. VERIFY   → agent-desktop snapshot --root @e3 --snapshot \u003Csnapshot_id> -i --compact\n   Re-drill the same region to confirm the state change.\n   Scoped invalidation: only @e3's subtree refs are replaced.\n\n5. REPEAT   → Continue drilling other regions or acting as needed.\n```\n\n**When to skip skeleton and use full snapshot instead:**\n- Simple apps with few elements (Finder, Calculator, TextEdit)\n- You already know the exact element name — use `find` instead\n- Surface snapshots (menus, sheets, alerts) — these are already focused\n\n**When skeleton shines:**\n- Dense Electron apps (Slack, VS Code, Discord, Notion) that are **already running** — for one you are launching fresh, `launch --cdp` plus a CDP client (agent-browser preferred) reads the web contents faster than any skeleton walk (see principle 15)\n- Any app where full snapshot exceeds ~50 refs\n- Multi-region workflows (sidebar + main content + toolbar)\n\n## Ref System\n\n- Refs are assigned depth-first and emitted with their snapshot, for example `@s8f3k2p9:e1`, `@s8f3k2p9:e2`, `@s8f3k2p9:e3`. Legacy bare refs require an explicit `--snapshot`.\n- An element gets a ref when it is addressable for an action: an interactive role (button, textfield, checkbox, link, menuitem, tab, slider, combobox, treeitem, cell, radiobutton, switch, ...) **or** any element advertising an action — so `scrollarea` (Scroll) and `disclosure` (Expand\u002FCollapse) are ref-able and `scroll`\u002F`expand`\u002F`collapse` can target them\n- A `SetFocus`-only affordance does not earn a ref on its own\n- In skeleton mode, each truncated branch exposes the deepest safely resolvable drill target using stable text, native ID, or bounds evidence; the nearest resolvable ancestor is used when the boundary itself is anonymous\n- Static text and non-actionable groups\u002Fcontainers remain in tree for context but have no ref\n- Refs are deterministic within a snapshot but NOT stable across snapshots if UI changed\n- Snapshot output uses qualified refs that embed `snapshot_id` and need no separate `--snapshot`; a session-owned ref still requires the same `--session` or `AGENT_DESKTOP_SESSION` scope because lookup never crosses namespaces\n- `last_refmap.json` is only a latest-snapshot inspection artifact. The command path uses snapshot-scoped storage.\n- After any action that changes UI, re-drill the affected region or re-snapshot\n- **Scoped invalidation:** re-drilling a qualified root ref only replaces refs from that root's previous drill — refs from other regions and the skeleton itself are preserved\n- **Strict resolution:** stale refs return `STALE_REF`; duplicate plausible targets return `AMBIGUOUS_TARGET` instead of choosing arbitrarily.\n- **Actionability:** every ref-addressed action checks its applicable live visibility, stability, enabled, editability, policy, supported-action, and hit-test requirements under one bounded budget before a single dispatch. Pointer actions focus before their final geometry read, re-resolve moving endpoints, and return `TIMEOUT` with `details.kind: \"actionability_timeout\"` instead of sending input after the deadline.\n- **Headless vs headed:** ref actions are strictly headless by default: semantic accessibility APIs only, with no focus stealing, cursor movement, or synthesized keyboard input. In headed mode, core focuses the exact ref window before dispatch; pointer actions also require a verified target point, while the adapter owns OS delivery. On macOS, `click`, `right-click`, `type`, `clear`, and `scroll` are physical-first; double\u002Ftriple-click, hover, and drag are physical-only; expand\u002Fcollapse and other semantic actions remain semantic. Raw `--xy` input has no window identity and never steals focus. `press` is explicit physical keyboard input; held-input commands (`key-down`, `key-up`, `mouse-down`, `mouse-up`) are reserved and fail closed in the stateless CLI.\n- **Sessions and tracing:** run `session start` once per task to create a manifest with `trace: on` (default), then pass its returned ID with `--session` or `AGENT_DESKTOP_SESSION`. Use `session start --screenshots` when you need replay artifacts (`artifacts: full`): pre\u002Fpost-action PNGs and refmap copies under the session trace directory (sensitive — treat exports like screenshots). Commands in that explicit scope record JSONL automatically to per-process segments under `~\u002F.agent-desktop\u002Fsessions\u002F\u003Cid>\u002Ftrace\u002F\u003Cpid>-\u003CprocTs>.jsonl` — no `--trace` on every call. Read traces back with `trace show` (bounded JSON for agents) or `trace export` (single-file HTML for humans). A session owns both its trace and its latest-snapshot namespace. Snapshot lookup never searches another namespace. **`--session \u003Cid>` alone** (no manifest from `session start`) selects only the snapshot namespace — existing callers see no surprise trace files. **`--trace \u003Cpath>`** still overrides to one atomic file for CI or one-offs. Activation precedence is `--session` > `AGENT_DESKTOP_SESSION` > no session; `session start` does not activate later processes. Multi-agent shared sessions: the harness passes the same session ID to every subagent. For independent macOS cursors use `session start --cursor --multi-agent` and assign each subagent a stable `AGENT_DESKTOP_AGENT_ID` or global `--agent-id` (flag wins). Desktop UI actions then require the ID; observations, clipboard operations, and administration do not. Three distinct IDs produce three cursors, in both headless and headed mode. Drags reuse the cursor’s curved motion and show a live accent-colored trail while held, fading after release; the ripple setting controls the trail. Physical pointer commands also show their agent’s overlay; the interaction lease serializes access to the shared OS pointer. Each agent acts on qualified refs from its own snapshot — implicit latest is not a cross-agent guarantee. Optional `--agent-id \u003Cid> cursor-overlay enable` styling is saved for that agent’s next presentation; no registration is needed. Disable\u002Fend stops every session cursor. Run `status` to see `session_id` and `tracing`. Trace lines include `ts_ms`, monotonic per-process `seq`, and redacted sensitive fields (`text`, `value`, `expected`, `name`, `username`, `description`, `label`, `query`, `secret`, `token`, `password`, `title`, `url`, `help`, `placeholder` → `{ \"redacted\": true }`). `--trace-strict` fails on trace setup and pre-action writes; post-action success traces are best-effort.\n\n## JSON Output Contract\n\nEvery command returns a JSON envelope on stdout:\n\n**Success:** `{ \"version\": \"2.4\", \"ok\": true, \"command\": \"snapshot\", \"data\": { ... } }`\n**Error:** `{ \"version\": \"2.4\", \"ok\": false, \"command\": \"click\", \"error\": { \"code\": \"STALE_REF\", \"message\": \"...\", \"suggestion\": \"...\" } }`\n\nThe `error` object may also carry an optional `details` object (e.g. the actionability report on an actionability failure, candidate summaries on `AMBIGUOUS_TARGET`, or the last observed state on a `wait` `TIMEOUT`). Parse errors leniently — `details` and future fields are additive, so do not reject responses with unknown keys.\n\nAn error also carries `disposition`, and that object decides whether a retry is safe:\n\n| Field | Values |\n|-------|--------|\n| `disposition.delivery` | `not_delivered`, `delivery_uncertain`, `delivered_unverified`, `delivered_verified`, `unknown` |\n| `disposition.retry` | `safe`, `unsafe`, `unknown` |\n\n**Retry or substitute an action only when `disposition.retry` is `safe`, and follow `recovery.strategy` only in that same case.** Only `not_delivered` is `safe`. Every other delivery value is `unsafe`, because the action may already have landed — repeating it would click, type, or submit twice. On an `unsafe` result, read `details.post_state` and `details.postcondition_satisfied` to decide what actually happened, then act on the observed state instead of repeating the command. A failure after preparatory scrolling carries `details.preparatory_scroll` and never authorizes an automatic retry.\n\nAn actionability failure on a hit-test action (`click`, `double-click`, `right-click`, `triple-click`, `hover`, `drag`) can carry a `receives_events` check with `reason: \"occluded by \u003Crole>\"` plus a structured `occluder: { \"role\", \"name\", \"bounds\" }` — another element is on top of the target. Bring the target window\u002Felement to the front (or dismiss the occluder) rather than blind-retrying; see `references\u002Fcommands-interaction.md` for the full check list.\n\nExit codes: `0` success, `1` structured error, `2` argument error.\n\n### Error Codes\n\n| Code | Meaning | Recovery |\n|------|---------|----------|\n| `PERM_DENIED` | Accessibility or Screen Recording permission not granted | Grant the named permission in System Settings |\n| `ELEMENT_NOT_FOUND` | Ref cannot be resolved against the live UI | Re-run snapshot, use fresh ref |\n| `APP_NOT_FOUND` | App not running | Launch it first |\n| `ACTION_FAILED` | Action rejected or its observed result contradicted the request | Inspect `disposition.retry`, `details.post_state`, and `details.after_action`; do not repeat or substitute an action after uncertain or unverified delivery |\n| `ACTION_NOT_SUPPORTED` | Element can't do this | Use different command |\n| `STALE_REF` | Ref could not be re-identified in the live UI | Use the `snapshot_id` returned with this ref; if the UI changed or the target disappeared, re-run `snapshot` \u002F `snapshot --skeleton` to get fresh refs |\n| `AMBIGUOUS_TARGET` | Multiple elements matched the old ref identity | Re-run snapshot and choose a more specific ref |\n| `SNAPSHOT_NOT_FOUND` | Snapshot ID is missing or expired | Run `snapshot` again and use the returned ID |\n| `POLICY_DENIED` | A physical\u002Fheaded path was blocked | Use an explicit mouse\u002Ffocus\u002Fkeyboard command if physical interaction is intended |\n| `APP_UNRESPONSIVE` | A read-only AX liveness probe also failed after an uncertain mutation response | Inspect with a fresh snapshot and wait for the app to recover before deciding whether to retry |\n| `WINDOW_NOT_FOUND` | No matching window | Check app name, use list-windows |\n| `PLATFORM_NOT_SUPPORTED` | Adapter method not implemented on this platform | Use a supported platform adapter |\n| `TIMEOUT` | Wait or actionability condition not met | Inspect `error.details.kind`; increase the command budget only after checking the last report, and use `AGENT_DESKTOP_CHAIN_TIMEOUT_MS` only for `chain_deadline` |\n| `INVALID_ARGS` | Bad arguments | Check command syntax |\n| `NOTIFICATION_NOT_FOUND` | Notification index no longer exists | Re-run list-notifications |\n| `INTERNAL` | Unexpected platform\u002FOS failure (e.g. event synthesis failed) | Read `message`\u002F`suggestion` for cleanup state, then retry once; persistent failures indicate an environment problem |\n\n`TIMEOUT` errors carry a `details` object whose `kind` field selects the schema. `kind: \"wait_timeout\"` includes `predicate`, `timeout_ms`, and `last_observed` or `last_error`, plus `ref`\u002F`title`\u002F`text_chars` depending on the wait mode. `kind: \"chain_deadline\"` includes `value_before`, `value_at_timeout`, `target`, and `mutated` (increment waits) or `wanted_expanded`\u002F`observed_expanded` (disclosure waits). `mutated: true` — or an unknown `observed_expanded` state — means re-read the element before retrying; `mutated: false` means the state did not change and retrying directly is safe.\n\n`details.kind: \"post_action_verification\"` means execution was followed by a contradictory or failed state read. The original read error code is preserved, so even `STALE_REF` or `TIMEOUT` can follow delivery. Inspect `post_state`, `after_action`, and `disposition.retry` before any retry or alternative action. Missing evidence alone is reported as successful `delivered_unverified` with `details.verification_scope: \"unavailable\"`, not as proof that the change failed.\n\n## Command Quick Reference (59 names, 55 operational)\n\n### Observation\n```\nagent-desktop snapshot --skeleton --app \"App\" -i --compact  # Skeleton overview (preferred)\nagent-desktop snapshot --root @s8f3k2p9:e3 -i --compact              # Drill into region\nagent-desktop snapshot --app \"App\" -i                       # Full tree (simple apps)\nagent-desktop snapshot --app \"App\" --surface menu -i        # Surface snapshot\nagent-desktop screenshot --app \"App\" out.png                # PNG screenshot\nagent-desktop find --app \"App\" --role button                # Search elements\nagent-desktop find --root @s8f3k2p9:e3 --role button        # Search one region only\nagent-desktop find --app \"App\" --surface menubar --name \"Save\" --first  # Search a menu\nagent-desktop get @e1 --snapshot \u003Csnapshot_id> --property text       # Read element property\nagent-desktop is @e1 --snapshot \u003Csnapshot_id> --property enabled     # Check element state\nagent-desktop list-surfaces --app \"App\"                     # Available surfaces\n```\n\nFor a visual demo on macOS, add `--debug --screenshot \u002Ftmp\u002Fvisual.html` to `snapshot` or `click`. The local HTML viewer has ref highlights and collapsible role groups with checkbox filters. Choose a new file; see [Visual debug](references\u002Fcommands-observation.md#visual-debug).\n\n### Interaction\n```\nagent-desktop click @e5 --snapshot \u003Csnapshot_id> # Headless semantic click\nagent-desktop --headed double-click @s8f3k2p9:e3 # physical double-click\nagent-desktop --headed triple-click @s8f3k2p9:e2 # physical triple-click\nagent-desktop right-click @s8f3k2p9:e5          # Right-click; inspect the resulting menu\u002Feffect separately\nagent-desktop type @e2 --snapshot \u003Csnapshot_id> \"hello\"  # Headless AX text insertion when supported\nagent-desktop set-value @s8f3k2p9:e2 \"new value\"         # Set value directly\nagent-desktop clear @s8f3k2p9:e2                         # Clear element value\nagent-desktop focus @s8f3k2p9:e2                         # Set keyboard focus\nagent-desktop select @s8f3k2p9:e4 \"Option B\"             # Select dropdown\u002Flist option\nagent-desktop toggle @s8f3k2p9:e6                        # Toggle checkbox\u002Fswitch\nagent-desktop check @s8f3k2p9:e6                         # Idempotent check\nagent-desktop uncheck @s8f3k2p9:e6                       # Idempotent uncheck\nagent-desktop expand @s8f3k2p9:e7                        # Expand disclosure\nagent-desktop collapse @s8f3k2p9:e7                      # Collapse disclosure\nagent-desktop scroll @s8f3k2p9:e1 --direction down       # Scroll element\nagent-desktop scroll-to @s8f3k2p9:e8                     # Scroll into view\n```\n\n### Keyboard & Mouse\n```\nagent-desktop press cmd+c                       # Key combo\nagent-desktop press return --app \"App\"          # Targeted key press\nagent-desktop --headed hover @s8f3k2p9:e5       # Explicit cursor movement\nagent-desktop --headed hover --xy 500,300       # Cursor to coordinates\nagent-desktop --headed drag --from @s8f3k2p9:e1 --to @s8f3k2p9:e5 # Drag between elements\nagent-desktop --headed mouse-click --xy 500,300 # Click at coordinates\nagent-desktop --headed mouse-move --xy 100,200  # Move cursor\n```\n\n`key-down`, `key-up`, `mouse-down`, and `mouse-up` return `ACTION_NOT_SUPPORTED` until a stateful daemon can own held-input lifetime. Use `press`, `mouse-click`, or `drag` instead.\n\n### App & Window\n```\nagent-desktop launch \"System Settings\"          # Launch; returns once running\nagent-desktop launch \"TextEdit\" --activate       # Also bring it forward and wait for a window\nagent-desktop launch \"Obsidian\" --cdp            # Fresh launch + verified Chrome DevTools Protocol port for web contents\nagent-desktop close-app \"TextEdit\"              # Quit gracefully\nagent-desktop close-app \"TextEdit\" --force      # Force quit; SIGKILL if SIGTERM does not exit\nagent-desktop list-windows --app \"Finder\"       # List windows\nagent-desktop list-apps                         # List running GUI apps\nagent-desktop focus-window --app \"Finder\"       # Bring to front\nagent-desktop resize-window --app \"App\" --width 800 --height 600\nagent-desktop move-window --app \"App\" --x 0 --y 0\nagent-desktop minimize --app \"App\"\nagent-desktop maximize --app \"App\"\nagent-desktop restore --app \"App\"\n```\n\nUse `--window-id \u003Cid>` from `list-windows` instead of `--app` when an app has multiple windows.\n\n### Notifications\n```\nagent-desktop --headed list-notifications                # Open center if needed, then list\nagent-desktop --headed list-notifications --app \"Slack\"  # Filter by app\nagent-desktop --headed list-notifications --text \"deploy\" --limit 5  # Filter by text\nagent-desktop --headed dismiss-notification 1 --expected-app Slack --expected-title \"Deploy complete\"\nagent-desktop --headed dismiss-all-notifications         # Dismiss all\nagent-desktop --headed dismiss-all-notifications --app \"Slack\"  # Dismiss all from app\nagent-desktop --headed notification-action 1 \"Reply\" --expected-app Slack --expected-title \"Deploy complete\"\n```\n\nEvery notification mutation requires global `--headed`; single-notification\nmutations also require an app or title fingerprint from the same listing.\nHeadless listing works only while Notification Center is already open.\n\n### Clipboard\n```\nagent-desktop clipboard-get                     # Read clipboard\nagent-desktop clipboard-set \"text\"              # Write to clipboard\nagent-desktop clipboard-clear                   # Clear clipboard\n```\n\n### Wait\n```\nagent-desktop wait 1000                         # Pause 1 second\nagent-desktop wait --element @e5 --snapshot \u003Csnapshot_id> --timeout 5000 # Wait for element\nagent-desktop wait --element @s8f3k2p9:e5 --predicate actionable --timeout 5000 # Wait until actionable\nagent-desktop wait --element @s8f3k2p9:e5 --predicate value --value \"Done\" --timeout 5000 # Wait for value\nagent-desktop wait --window \"Title\"             # Wait for window\nagent-desktop wait --text \"Done\" --app \"App\"    # Wait for text\nagent-desktop wait --menu --app \"App\"           # Wait for menu surface\nagent-desktop wait --menu-closed --app \"App\"    # Wait for menu dismissal\nagent-desktop wait --notification --app \"App\"   # Wait for new notification\n```\n\n### System\n```\nagent-desktop session start [--name LABEL] [--screenshots] [--no-trace] [--cursor [--multi-agent]]  # Creates a session; pass the returned ID explicitly\nagent-desktop session end [id]                                      # Seal manifest\nagent-desktop session list                                          # List session manifests\nagent-desktop session gc [--older-than SECS] [--ended]              # Reclaim ended\u002Fstale sessions\nagent-desktop --session \u003Cid> cursor-overlay enable [--multi-agent] [--label TEXT] [--max-words N] [--fill HEX] [--rim HEX] [--accent HEX] [--size N] [--no-ripple] [--no-highlight]\nagent-desktop --session \u003Cid> --agent-id ID cursor-overlay enable [--label TEXT] [--max-words N] [--fill HEX] [--rim HEX] [--accent HEX] [--size N] [--no-ripple] [--no-highlight]\nexport AGENT_DESKTOP_SESSION=\u003Cid>\nagent-desktop cursor-overlay disable                                # Stop all cursors in the selected session\nagent-desktop trace show [--limit N] [--event PREFIX]               # Merge trace segments (default tail 500; 0 = all)\nagent-desktop trace export [--out path.html] [--limit N]            # Self-contained HTML viewer (default tail 5000)\nagent-desktop status                            # Health, session_id, tracing, artifacts, permissions\nagent-desktop permissions                       # Check permission\nagent-desktop permissions --request             # Request missing permissions in an isolated helper\nagent-desktop version                           # Version info (always JSON envelope)\nagent-desktop batch '[...]' --stop-on-error     # Batch uses the same typed command path as CLI\nagent-desktop skills                            # List bundled skill docs\nagent-desktop skills get desktop --full         # Load this skill + all references\n```\n\n## Key Principles for Agents\n\n1. **Find known targets; skeleton unknown structure.** If role or exact name is known, use targeted `find` first. Use `--skeleton -i --compact` when the region is unknown, then drill with `--root @ref`. For fresh Chromium launches, prefer `launch --cdp` plus a CDP client.\n2. **Use `-i --compact` flags.** Filters to interactive elements and collapses empty wrappers, minimizing tokens.\n3. **Refs are snapshot-scoped.** Keep `snapshot_id` for deterministic multi-step use; re-drill the affected region after any UI-changing action. Scoped invalidation keeps other refs intact.\n4. **Prefer refs over coordinates.** `click @s8f3k2p9:e5` > `agent-desktop --headed mouse-click --xy 500,300`.\n5. **Use `wait` for async UI.** After launch\u002Fdialog triggers, wait for expected state.\n6. **Check permissions first.** Run `permissions` on first use; screenshots also need Screen Recording.\n7. **Handle errors.** Branch on `error.code` only — `error.message` and `error.suggestion` text is informational and may change between versions.\n8. **Scope targeted searches.** Pair known names with role and `--exact`; use `--limit 2` before a mutation when uniqueness is not guaranteed. Narrow with `--root @ref` for one region or `--surface menubar` for a menu.\n9. **Use surfaces for overlays.** `snapshot --surface menu` for menus, `--surface sheet` for dialogs. Never `--skeleton` for surfaces — they're already focused. Reach one item inside an overlay with `find --surface`, not a full surface snapshot.\n10. **Read `data.surfaces` after acting.** An action that opens a sheet, menu, or alert reports it there. Target that overlay next instead of searching windows for what changed.\n11. **Batch for performance.** Multiple commands in one invocation.\n12. **Headless by default.** Ref actions use semantic AX paths and block silent focus stealing, cursor movement, keyboard synthesis, and pasteboard insertion. Use `--headed` only when exact-window focus or physical delivery is intended; raw coordinates never imply focus.\n13. **Start a session once per run.** `session start` creates the manifest; pass its returned ID through `AGENT_DESKTOP_SESSION` for the run or `--session \u003Cid>` for one command. It does not activate later processes implicitly.\n14. **Trace hard failures.** With an active trace-enabled session, segments are written automatically. Add `--trace \u002Ftmp\u002Fagent-desktop.jsonl` only when you need a single override file (CI, one-offs). Check `status` when unsure whether tracing is active.\n15. **Relocate state with `AGENT_DESKTOP_HOME`.** When set, the env value is the state root itself — sessions, refmaps, traces, and locks all live under it, for every subcommand. Default stays `~\u002F.agent-desktop`. The value must be an absolute path; a relative or empty value fails with `INVALID_ARGS` before any command runs. `status` reports the resolved root as `state_root`. Explicit output paths (`screenshot --out`, `--trace \u003Cpath>`) are never re-rooted.\n16. **Chromium-app strategy.** The accessibility path is the default, and the only option for already-running apps and for native surfaces (menus, dialogs, windows). `launch --cdp` plus a CDP client (agent-browser preferred; any CDP client works) is the opt-in fast path for a Chromium app's web contents, when a fresh launch is acceptable.\n",{"name":5,"tags":24,"version":25,"description":7,"requirements":26},"computer-use, desktop-automation, accessibility, ai-agent, gui-automation, cli","0.4.0",[5],"main","d69096e239f2a89aabc2cd078c47664a9d3b1e11","06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop",3,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts","https:\u002F\u002Fgithub.com\u002Flza6","个人vx：Tf00798\r\n个人✈：@TFGY999","2026-10-08 14:29:22",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add lza6\u002FArmor-piercing-system-prompts --skill agent-desktop",{"tool":41,"command":42},"bunx","bunx skills add lza6\u002FArmor-piercing-system-prompts --skill agent-desktop",{"tool":44,"command":45},"pnpm","pnpm dlx skills add lza6\u002FArmor-piercing-system-prompts --skill agent-desktop","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002FSKILL.md",true,[49,55,59,63,67],{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fcommands-interaction.md","REFERENCE","参考文档",30135,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002Freferences\u002Fcommands-interaction.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fcommands-observation.md",14351,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002Freferences\u002Fcommands-observation.md",{"path":60,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fcommands-system.md",41436,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002Freferences\u002Fcommands-system.md",{"path":64,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Fmacos.md",15600,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002Freferences\u002Fmacos.md",{"path":68,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Fworkflows.md",15996,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F06-前端与设计\u002Fagent-desktop-lahfir__agent-desktop\u002Freferences\u002Fworkflows.md",[72,79,84,91,98,105],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7FFG485KY83TD6HSC4YPCMC","obsidian-clipper-template-creator","Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator\u002FSKILL.md",[],[],{"skillNo":80,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7FFG0T6AZ0STEJPSB3CX84K","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator-antigravity-awesome-skills-main\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7FFFY0QEM14SKWPDYGMXM2P","python-api","Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP\u002FmAP semantics, and source-style import diagnostics.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Fpython-api\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M7FFFVZQZ2GJ0C0TGP7JHD20","file-evaluation","Folder-based PASCAL VOC AP\u002FmAP evaluation from ground-truth and detection text files.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Ffile-evaluation\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":19},"01M7FFFSFNYSE77SJ6PE1CK2DA","object-detection-metrics","Guides legacy Object-Detection-Metrics PASCAL VOC AP\u002FmAP evaluation from detection text folders and direct Python API classes.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":19},"01M7FFFP0GCK1RVXBCPQ8APBMT","nx-workspace-patterns","Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fnx-workspace-patterns\u002FSKILL.md",[],[]]