[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7D55XSWDS5ACPHHMEVNZVH4":3,"skill-same:01M7D55XSWDS5ACPHHMEVNZVH4":48},{"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":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7D55XSWDS5ACPHHMEVNZVH4","computer-use",null,"Use when a task needs a native desktop app's own UI or the OS. For anything inside a web page, use Browser Use. Main agent only.","zai-org\u002FZCode","zai-org","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F223098841?v=4","01M7D3Y10287Y0CNVHSNZ4GD03","Z.ai","01M7D3Y10SKN81G21P442YTCYP",8689,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fapps\u002Fzcode-cli\u002Fpackages\u002Fzcode-cua-plugin\u002Fskills\u002Fcomputer-use\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: computer-use\ndescription: \"Use when a task needs a native desktop app's own UI or the OS. For anything inside a web page, use Browser Use. Main agent only.\"\n---\n\n# Computer Use\n\nRead or operate the UI of native apps on the user's computer.\n\n- Prefer a dedicated connector, API, CLI or skill when one can complete the task.\n- For browser and web tasks, use Browser Use instead.\n- Do not use AppleScript, `osascript`, JXA, System Events, shell commands, or any\n  other UI-automation technology unless the user explicitly asks for that\n  technology.\n- Main agent only. Never delegate Computer Use to a subagent.\n\n## Bootstrap every call\n\nEach `mcp__node_repl__js` call runs in a fresh Worker. Globals, imports, module\ncache and any binding are gone by the next call, so `const app` does not survive\nthe end of the cell. The UI state does survive, so re-binding in the next cell is\ncheap.\n\nPut the bootstrap and the actions in the **same** cell, bootstrap first:\n\n```js\nconst root =\n  process.env.ZCODE_CUA_PLUGIN_ROOT ??\n  process.env.ZCODE_PLUGIN_ROOT ??\n  process.env.CLAUDE_PLUGIN_ROOT;\nconst { join } = await import(\"node:path\");\nconst { pathToFileURL } = await import(\"node:url\");\nconst { setupComputerUseRuntime } = await import(\n  pathToFileURL(join(root, \"scripts\", \"computer-use-client.mjs\")).href,\n);\nawait setupComputerUseRuntime({ globals: globalThis });\n```\n\n## Accessibility first\n\nAccessibility is the primary action path. It is semantic, precise, works on a\nbackground app and does not steal the user's focus.\n\n1. Observe, then search the returned tree for the target by its role, name,\n   title, value or other visible identity.\n2. When a matching element exists, act on it by **index**. For a control that\n   advertises a semantic action, `performSecondaryAction` is also correct.\n3. For a settable element prefer `setValue` over typing or pasting. Reach for\n   `paste` only when the target is not settable or the content is rich text.\n4. Keyboard input is the fallback: use `pressKey` only when no element expresses\n   the operation, or the user asked for keyboard interaction. Coordinates are the\n   last fallback, for canvas, games and Electron content accessibility cannot see.\n\nDo not replace an available element action with a keyboard shortcut just because\nthe shortcut is shorter. Do not run both the accessibility and visual paths for\nthe same action.\n\n**Observation works on a background app, screenshots included** — on any\ndisplay, including windows at negative coordinates.\n`has_image: false` means the call did not ask for pixels (`getAXState`), never\nthat capture failed.\n\nSuccess means the API accepted an action, not that the app acted. Typing into a\nweb-content editor can be accepted and change nothing, so re-observe to confirm\nthe text landed.\n\n## API\n\n```typescript\ntype Vec2 = [x: number, y: number];\ntype ObservationOptions = { emit?: boolean };\ntype StateOptions = ObservationOptions & { disableDiffing?: boolean };\ntype StateAndScreenshot = { state: string; screenshot?: Uint8Array };\ntype Direction = \"up\" | \"down\" | \"left\" | \"right\" | \"u\" | \"d\" | \"l\" | \"r\";\ntype MouseButton = \"left\" | \"right\" | \"middle\" | \"l\" | \"r\" | \"m\";\ntype SelectionType = \"text\" | \"cursor_before\" | \"cursor_after\";\ntype Strategy = \"auto\" | \"a11y\" | \"event\";\n\ntype ClickOptions = {\n  mouseButton?: MouseButton;\n  clickCount?: number;\n  modifiers?: string;\n  strategy?: Strategy;\n};\ntype SelectTextOptions = { prefix?: string; suffix?: string; selectionType?: SelectionType };\ntype PasteOptions = { format?: \"text\" | \"md\" | \"html\" };\ntype PressKeyOptions = { holdSeconds?: number; strategy?: Strategy };\n\ninterface Target {\n  getAXState(options?: StateOptions): Promise\u003Cstring>;\n  getScreenshot(options?: ObservationOptions): Promise\u003CUint8Array>;\n  getAXStateAndScreenshot(options?: StateOptions): Promise\u003CStateAndScreenshot>;\n  elements(): Promise\u003C{ index: number; kind: string; title: string | null; value: string | null; actions: string[] }[]>;\n\n  paste(text: string, options?: PasteOptions): Promise\u003Cvoid>;\n  click(target: number | Vec2, options?: ClickOptions): Promise\u003Cvoid>;\n  drag(from: number | Vec2, to: number | Vec2, options?: { modifiers?: string }): Promise\u003Cvoid>;\n  pressKey(key: string, options?: PressKeyOptions): Promise\u003Cvoid>;\n  scroll(target: number | Vec2, direction: Direction, pages?: number): Promise\u003Cvoid>;\n  selectText(elementIndex: number, text: string, options?: SelectTextOptions): Promise\u003Cvoid>;\n  setValue(elementIndex: number, value: string): Promise\u003Cvoid>;\n  typeText(text: string): Promise\u003Cvoid>;\n  performSecondaryAction(elementIndex: number, action: string): Promise\u003Cvoid>;\n}\n\ninterface App extends Target {}\n\ntype AppRef = { name?: string; bundle_id?: string; pid?: number; window_id?: number };\ntype AppInfo = { pid: number; name: string | null; bundle_id: string | null; active: boolean };\ntype State = { apps: AppInfo[] };\n\ndeclare const agent: {\n  computerUse: {\n    getState(options?: ObservationOptions): Promise\u003CState>;\n    getApp(target: string | AppRef): Promise\u003CApp>;\n    listApps(options?: ObservationOptions): Promise\u003CAppInfo[]>;\n    computer: Record\u003Cstring, (args: object) => Promise\u003Cunknown>>;\n\n    requestAccess(capabilities?: string[]): Promise\u003CRecord\u003Cstring, unknown>>;\n    stop(reason?: string): Promise\u003Cvoid>;\n  };\n};\n```\n\nThe full reference is `agent.documentation.get(\"computer-use\")`, fetched on demand;\nread it only for an argument shape or response field this page does not give.\n\n## The loop\n\nObserve once, act, then observe again before deciding the next step.\n\n`agent.computerUse.getApp(...)` binds an app and shows nothing; call `getAXState`\nwhen you need to see its state. Binding also launches it if not running; there is\nno separate launch tool. Its argument is a display name or a bundle identifier —\nthe same strings `listApps()` returns — or an `AppRef`.\n\nWhen the user names an application, copy it character-for-character into the app\nidentifier. Do not translate, localize, normalize, shorten, or remove a suffix:\n`{\"name\":\"网易云音乐app\"}` is not `{\"name\":\"网易云音乐\"}`; `{\"name\":\"日历\"}` is not\n`{\"name\":\"Calendar\"}`. A rewritten name resolves to a different app or to nothing,\nand the failure reads \"app not found\". If the exact string does not resolve, call\n`agent.computerUse.listApps()` once and pick the matching identifier.\n\nBatch related actions and a single closing observation into one cell:\n\n```js\nconst app = await agent.computerUse.getApp(\"Notes\");\nawait app.click(box);\nawait app.typeText(\"hello\");\nawait app.pressKey(\"Return\");\nawait app.getAXState();\n```\n\nAn element index addresses that app's latest observation, so several actions may\nreuse one index without re-observing between them — click an index, then type into\nit, in the same cell. Observing renumbers the tree, so take indices from the newest\none. A vanished element fails closed with `ELEMENT_UNAVAILABLE`.\n\nThe tree comes back as a diff only against a tree this cell already showed you,\nlisting the elements that were removed, added or changed; unchanged rows are\nomitted and their indices stay valid. The first tree after binding, and the first\nafter `getScreenshot` or `elements()`, are always complete. Pass\n`{ disableDiffing: true }` for a full tree at any point. If a standalone\nobservation reports no change, do not immediately repeat it without an\nintervening action.\n\nA large tree is trimmed by priority (ancestors kept), the header says so, and\nindices then skip numbers. `app.elements()` returns every element with its index,\ntrimmed ones included — filter it in JS, never guess an index.\n\nA capture is scoped to one window: without a `window_id` the main\u002Fkey window is\nre-resolved every observation, so a modal that just opened becomes the captured\nwindow. When an action fails or the tree reads like another part of the app, check\nthe observation's `window` — a dialog shows up there. Read it, then act on it, or\ndismiss it (Escape or its own cancel) and observe again. A missing element is not\nproof the action worked. Pin one with `getApp({pid, window_id})`; `list_windows`\nhas the id.\n\n## Output\n\nObservations display themselves: `getAXState`, `getScreenshot`,\n`getAXStateAndScreenshot`, `getState` and `listApps` emit their own result.\nNever pass their return value to `nodeRepl.write(...)` or\n`nodeRepl.emitImage(...)`: a second raster in one result breaks the one-raster\nrule and the frame is removed entirely, so you end up with no picture at all.\nPass `{ emit: false }` to suppress the display and still receive the value.\n\nAction methods display nothing.\n\n## Coordinates\n\nChoose `x` and `y` only by looking at the current returned raster, with\n`0 \u003C= x \u003C width` and `0 \u003C= y \u003C height` for that raster. Submit those integers\nunchanged; CUA binds the current raster internally and owns every transform from\nthe returned raster to native dispatch. Element and window bounds are diagnostic\nglobal screen points and must never be copied into a coordinate. When visual\nfallback begins, discard coordinate-like numbers from earlier text or\naccessibility results.\n\nAct on the current raster when the target is clear; if it is too small or ambiguous,\nre-observe rather than guessing at geometry.\n\nA pointer action accepted with no change usually means the app acted where the real\npointer sits: repeating it will not help — use an element index or the keyboard.\n\nA coordinate refusal may name an unexpected owner, or say the frame is stale — the\nwindow moved, resized or was replaced. Observe again for a current raster, or act on\nan element index, which does not depend on window geometry. Never move, resize or\nclose a window to make a coordinate land.\n\n## Keyboard\n\n`pressKey` takes a key or a `+`-separated chord and accepts both short names and\nX keysym style: `\"a\"`, `\"Return\"`, `\"Tab\"`, `\"Control_L+a\"`, `\"super+c\"`, `\"Up\"`.\nmacOS uses `cmd`; Linux and Windows use `ctrl`. Use `{ holdSeconds }` to hold a\nkey or chord for a duration rather than simulating repeated presses.\n\nBind keyboard input to an app or element; never send it unbound. `paste` is for\nrich text, or a target `setValue` cannot set — not for plain text a settable\nelement accepts.\n\n`performSecondaryAction` accepts only an action the element advertises in the\ncurrent tree. Do not guess an action name.\n\nAt most one element is `focused` — the one holding keyboard focus; absent means\nundetermined.\n\n`selectText` locates text inside an editable element. Use `prefix`\u002F`suffix` to\ndisambiguate repeated matches and `selectionType` to place the cursor instead of\nselecting. An ambiguous match is refused rather than resolved to the first hit.\n\n## Waiting\n\nObservations wait for the UI to settle before capturing. Do not pause or delay\nbefore reading state — no `setTimeout`, no polling loop.\n\n## Errors and stopping\n\nActions resolve to `undefined` on success and throw `ComputerUseError` otherwise:\n\n- `code` — `PERMISSION_DENIED`, `NOT_AUTHORIZED`, `APP_NOT_FOUND`,\n  `AMBIGUOUS_APP`, `LAUNCH_FAILED`, `INVALID_APP`, `ELEMENT_UNAVAILABLE`,\n  `STALE_STATE`, `NOT_SETTABLE`, `NOT_SELECTABLE`, `ACTION_UNAVAILABLE`,\n  `FOREGROUND_REQUIRED`, `CONTROLLER_BUSY`, `CONTROL_STOPPED`, `SCREEN_LOCKED`,\n  `HELPER_UNAVAILABLE`, `VERSION_MISMATCH`, `TIMEOUT`,\n  `STRUCTURED_STATE_UNAVAILABLE`, `INTERNAL`.\n- `actionSent` — whether the action may already have reached the app. Retry a\n  non-idempotent action only when this is `false`; otherwise observe first and\n  decide from what you see.\n- `retry` — `\"reobserve\"`, `\"retry\"` or `\"never\"`.\n\n`CONTROLLER_BUSY` means another live ZCode Computer Use session owns input. It is\nnever retryable: report the owner from the error and ask the user to close that\nsession.\n\nStop immediately after `agent.computerUse.stop()`, a kill switch, a permission\nrefusal, or a non-retryable error. Do not switch to a different UI-automation\ntechnology after an access refusal.\n\nPersist until the request is actually complete. Attempting an action is not\ncompletion: verify the returned state visibly shows the result. If it is unchanged\nor only intermediate, try another approach. Respond only when the requested state\nis visibly present, or explain a concrete blocker you cannot resolve.\n\n## Tool surface\n\n`agent.computerUse.computer.\u003Ctool>(args)` is the low-level surface. Prefer the\nbound-object API above; reach for a tool only for what the API does not\nexpress — window enumeration, key repeat, or reading state back in the same\ncall. Arguments are strict: an undeclared key is refused. Each tool takes **one**\narguments object — the names below are its keys, not positional parameters:\n`get_app_state({ app_ref: { bundle_id: \"com.apple.Notes\" }, include_screenshot: true })`.\n\nName an app as the OS lists it (Windows: the Start-menu name, not a window title).\nNothing takes the user's focus, except on Windows: launching a non-packaged app\ndoes, and `include_screenshot=true` un-minimizes — a minimized tree is fully\nusable, so keep the default.\n\n```\nlist_apps({})\nlist_windows({app_ref})\nget_app_state({app_ref, include_screenshot?=false, disable_diffing?=false})\n\nleft_click({target, mouse_button?=\"left\", click_count?=1, modifiers?=\"\",\n           strategy?, app_ref?, return_state?})\nleft_click_drag({from_target, to, modifiers?=\"\", strategy?, app_ref?,\n                return_state?})\nscroll({target, scroll_direction, scroll_amount, strategy?, app_ref?,\n       return_state?})\n\ntype({text, target?, app_ref?, strategy?, return_state?})\nset_value({target, value, strategy?, app_ref?, return_state?})\nselect_text({target, text_range?, app_ref?, return_state?})\nkey({text, repeat?, hold_seconds?, app_ref?, strategy?, return_state?})\npaste({text, format?=\"text\", app_ref?, return_state?})\nperform_action({target, action, app_ref?, return_state?})\n\nrequest_access({capabilities?})\nstop_computer_control({reason?})\n```\n\nArgument shapes: `app_ref` \u002F `app` is an `AppRef`, but a bare string here is\nread as a bundle id, so pass `{name: \"Notes\"}` for a display name.\n`scroll_direction` is `up|down|left|right`, `scroll_amount` is pages, `strategy`\nis `auto|a11y|event`, and `return_state` is `compact|full|none` to return the app\nstate in the same call. For `target`, `text_range`, `modifiers` and the response\nshapes, see `nodeRepl.write(await agent.documentation.get(\"computer-use\"))`.\n","# Computer Use\n\nRead or operate the UI of native apps on the user's computer.\n\n- Prefer a dedicated connector, API, CLI or skill when one can complete the task.\n- For browser and web tasks, use Browser Use instead.\n- Do not use AppleScript, `osascript`, JXA, System Events, shell commands, or any\n  other UI-automation technology unless the user explicitly asks for that\n  technology.\n- Main agent only. Never delegate Computer Use to a subagent.\n\n## Bootstrap every call\n\nEach `mcp__node_repl__js` call runs in a fresh Worker. Globals, imports, module\ncache and any binding are gone by the next call, so `const app` does not survive\nthe end of the cell. The UI state does survive, so re-binding in the next cell is\ncheap.\n\nPut the bootstrap and the actions in the **same** cell, bootstrap first:\n\n```js\nconst root =\n  process.env.ZCODE_CUA_PLUGIN_ROOT ??\n  process.env.ZCODE_PLUGIN_ROOT ??\n  process.env.CLAUDE_PLUGIN_ROOT;\nconst { join } = await import(\"node:path\");\nconst { pathToFileURL } = await import(\"node:url\");\nconst { setupComputerUseRuntime } = await import(\n  pathToFileURL(join(root, \"scripts\", \"computer-use-client.mjs\")).href,\n);\nawait setupComputerUseRuntime({ globals: globalThis });\n```\n\n## Accessibility first\n\nAccessibility is the primary action path. It is semantic, precise, works on a\nbackground app and does not steal the user's focus.\n\n1. Observe, then search the returned tree for the target by its role, name,\n   title, value or other visible identity.\n2. When a matching element exists, act on it by **index**. For a control that\n   advertises a semantic action, `performSecondaryAction` is also correct.\n3. For a settable element prefer `setValue` over typing or pasting. Reach for\n   `paste` only when the target is not settable or the content is rich text.\n4. Keyboard input is the fallback: use `pressKey` only when no element expresses\n   the operation, or the user asked for keyboard interaction. Coordinates are the\n   last fallback, for canvas, games and Electron content accessibility cannot see.\n\nDo not replace an available element action with a keyboard shortcut just because\nthe shortcut is shorter. Do not run both the accessibility and visual paths for\nthe same action.\n\n**Observation works on a background app, screenshots included** — on any\ndisplay, including windows at negative coordinates.\n`has_image: false` means the call did not ask for pixels (`getAXState`), never\nthat capture failed.\n\nSuccess means the API accepted an action, not that the app acted. Typing into a\nweb-content editor can be accepted and change nothing, so re-observe to confirm\nthe text landed.\n\n## API\n\n```typescript\ntype Vec2 = [x: number, y: number];\ntype ObservationOptions = { emit?: boolean };\ntype StateOptions = ObservationOptions & { disableDiffing?: boolean };\ntype StateAndScreenshot = { state: string; screenshot?: Uint8Array };\ntype Direction = \"up\" | \"down\" | \"left\" | \"right\" | \"u\" | \"d\" | \"l\" | \"r\";\ntype MouseButton = \"left\" | \"right\" | \"middle\" | \"l\" | \"r\" | \"m\";\ntype SelectionType = \"text\" | \"cursor_before\" | \"cursor_after\";\ntype Strategy = \"auto\" | \"a11y\" | \"event\";\n\ntype ClickOptions = {\n  mouseButton?: MouseButton;\n  clickCount?: number;\n  modifiers?: string;\n  strategy?: Strategy;\n};\ntype SelectTextOptions = { prefix?: string; suffix?: string; selectionType?: SelectionType };\ntype PasteOptions = { format?: \"text\" | \"md\" | \"html\" };\ntype PressKeyOptions = { holdSeconds?: number; strategy?: Strategy };\n\ninterface Target {\n  getAXState(options?: StateOptions): Promise\u003Cstring>;\n  getScreenshot(options?: ObservationOptions): Promise\u003CUint8Array>;\n  getAXStateAndScreenshot(options?: StateOptions): Promise\u003CStateAndScreenshot>;\n  elements(): Promise\u003C{ index: number; kind: string; title: string | null; value: string | null; actions: string[] }[]>;\n\n  paste(text: string, options?: PasteOptions): Promise\u003Cvoid>;\n  click(target: number | Vec2, options?: ClickOptions): Promise\u003Cvoid>;\n  drag(from: number | Vec2, to: number | Vec2, options?: { modifiers?: string }): Promise\u003Cvoid>;\n  pressKey(key: string, options?: PressKeyOptions): Promise\u003Cvoid>;\n  scroll(target: number | Vec2, direction: Direction, pages?: number): Promise\u003Cvoid>;\n  selectText(elementIndex: number, text: string, options?: SelectTextOptions): Promise\u003Cvoid>;\n  setValue(elementIndex: number, value: string): Promise\u003Cvoid>;\n  typeText(text: string): Promise\u003Cvoid>;\n  performSecondaryAction(elementIndex: number, action: string): Promise\u003Cvoid>;\n}\n\ninterface App extends Target {}\n\ntype AppRef = { name?: string; bundle_id?: string; pid?: number; window_id?: number };\ntype AppInfo = { pid: number; name: string | null; bundle_id: string | null; active: boolean };\ntype State = { apps: AppInfo[] };\n\ndeclare const agent: {\n  computerUse: {\n    getState(options?: ObservationOptions): Promise\u003CState>;\n    getApp(target: string | AppRef): Promise\u003CApp>;\n    listApps(options?: ObservationOptions): Promise\u003CAppInfo[]>;\n    computer: Record\u003Cstring, (args: object) => Promise\u003Cunknown>>;\n\n    requestAccess(capabilities?: string[]): Promise\u003CRecord\u003Cstring, unknown>>;\n    stop(reason?: string): Promise\u003Cvoid>;\n  };\n};\n```\n\nThe full reference is `agent.documentation.get(\"computer-use\")`, fetched on demand;\nread it only for an argument shape or response field this page does not give.\n\n## The loop\n\nObserve once, act, then observe again before deciding the next step.\n\n`agent.computerUse.getApp(...)` binds an app and shows nothing; call `getAXState`\nwhen you need to see its state. Binding also launches it if not running; there is\nno separate launch tool. Its argument is a display name or a bundle identifier —\nthe same strings `listApps()` returns — or an `AppRef`.\n\nWhen the user names an application, copy it character-for-character into the app\nidentifier. Do not translate, localize, normalize, shorten, or remove a suffix:\n`{\"name\":\"网易云音乐app\"}` is not `{\"name\":\"网易云音乐\"}`; `{\"name\":\"日历\"}` is not\n`{\"name\":\"Calendar\"}`. A rewritten name resolves to a different app or to nothing,\nand the failure reads \"app not found\". If the exact string does not resolve, call\n`agent.computerUse.listApps()` once and pick the matching identifier.\n\nBatch related actions and a single closing observation into one cell:\n\n```js\nconst app = await agent.computerUse.getApp(\"Notes\");\nawait app.click(box);\nawait app.typeText(\"hello\");\nawait app.pressKey(\"Return\");\nawait app.getAXState();\n```\n\nAn element index addresses that app's latest observation, so several actions may\nreuse one index without re-observing between them — click an index, then type into\nit, in the same cell. Observing renumbers the tree, so take indices from the newest\none. A vanished element fails closed with `ELEMENT_UNAVAILABLE`.\n\nThe tree comes back as a diff only against a tree this cell already showed you,\nlisting the elements that were removed, added or changed; unchanged rows are\nomitted and their indices stay valid. The first tree after binding, and the first\nafter `getScreenshot` or `elements()`, are always complete. Pass\n`{ disableDiffing: true }` for a full tree at any point. If a standalone\nobservation reports no change, do not immediately repeat it without an\nintervening action.\n\nA large tree is trimmed by priority (ancestors kept), the header says so, and\nindices then skip numbers. `app.elements()` returns every element with its index,\ntrimmed ones included — filter it in JS, never guess an index.\n\nA capture is scoped to one window: without a `window_id` the main\u002Fkey window is\nre-resolved every observation, so a modal that just opened becomes the captured\nwindow. When an action fails or the tree reads like another part of the app, check\nthe observation's `window` — a dialog shows up there. Read it, then act on it, or\ndismiss it (Escape or its own cancel) and observe again. A missing element is not\nproof the action worked. Pin one with `getApp({pid, window_id})`; `list_windows`\nhas the id.\n\n## Output\n\nObservations display themselves: `getAXState`, `getScreenshot`,\n`getAXStateAndScreenshot`, `getState` and `listApps` emit their own result.\nNever pass their return value to `nodeRepl.write(...)` or\n`nodeRepl.emitImage(...)`: a second raster in one result breaks the one-raster\nrule and the frame is removed entirely, so you end up with no picture at all.\nPass `{ emit: false }` to suppress the display and still receive the value.\n\nAction methods display nothing.\n\n## Coordinates\n\nChoose `x` and `y` only by looking at the current returned raster, with\n`0 \u003C= x \u003C width` and `0 \u003C= y \u003C height` for that raster. Submit those integers\nunchanged; CUA binds the current raster internally and owns every transform from\nthe returned raster to native dispatch. Element and window bounds are diagnostic\nglobal screen points and must never be copied into a coordinate. When visual\nfallback begins, discard coordinate-like numbers from earlier text or\naccessibility results.\n\nAct on the current raster when the target is clear; if it is too small or ambiguous,\nre-observe rather than guessing at geometry.\n\nA pointer action accepted with no change usually means the app acted where the real\npointer sits: repeating it will not help — use an element index or the keyboard.\n\nA coordinate refusal may name an unexpected owner, or say the frame is stale — the\nwindow moved, resized or was replaced. Observe again for a current raster, or act on\nan element index, which does not depend on window geometry. Never move, resize or\nclose a window to make a coordinate land.\n\n## Keyboard\n\n`pressKey` takes a key or a `+`-separated chord and accepts both short names and\nX keysym style: `\"a\"`, `\"Return\"`, `\"Tab\"`, `\"Control_L+a\"`, `\"super+c\"`, `\"Up\"`.\nmacOS uses `cmd`; Linux and Windows use `ctrl`. Use `{ holdSeconds }` to hold a\nkey or chord for a duration rather than simulating repeated presses.\n\nBind keyboard input to an app or element; never send it unbound. `paste` is for\nrich text, or a target `setValue` cannot set — not for plain text a settable\nelement accepts.\n\n`performSecondaryAction` accepts only an action the element advertises in the\ncurrent tree. Do not guess an action name.\n\nAt most one element is `focused` — the one holding keyboard focus; absent means\nundetermined.\n\n`selectText` locates text inside an editable element. Use `prefix`\u002F`suffix` to\ndisambiguate repeated matches and `selectionType` to place the cursor instead of\nselecting. An ambiguous match is refused rather than resolved to the first hit.\n\n## Waiting\n\nObservations wait for the UI to settle before capturing. Do not pause or delay\nbefore reading state — no `setTimeout`, no polling loop.\n\n## Errors and stopping\n\nActions resolve to `undefined` on success and throw `ComputerUseError` otherwise:\n\n- `code` — `PERMISSION_DENIED`, `NOT_AUTHORIZED`, `APP_NOT_FOUND`,\n  `AMBIGUOUS_APP`, `LAUNCH_FAILED`, `INVALID_APP`, `ELEMENT_UNAVAILABLE`,\n  `STALE_STATE`, `NOT_SETTABLE`, `NOT_SELECTABLE`, `ACTION_UNAVAILABLE`,\n  `FOREGROUND_REQUIRED`, `CONTROLLER_BUSY`, `CONTROL_STOPPED`, `SCREEN_LOCKED`,\n  `HELPER_UNAVAILABLE`, `VERSION_MISMATCH`, `TIMEOUT`,\n  `STRUCTURED_STATE_UNAVAILABLE`, `INTERNAL`.\n- `actionSent` — whether the action may already have reached the app. Retry a\n  non-idempotent action only when this is `false`; otherwise observe first and\n  decide from what you see.\n- `retry` — `\"reobserve\"`, `\"retry\"` or `\"never\"`.\n\n`CONTROLLER_BUSY` means another live ZCode Computer Use session owns input. It is\nnever retryable: report the owner from the error and ask the user to close that\nsession.\n\nStop immediately after `agent.computerUse.stop()`, a kill switch, a permission\nrefusal, or a non-retryable error. Do not switch to a different UI-automation\ntechnology after an access refusal.\n\nPersist until the request is actually complete. Attempting an action is not\ncompletion: verify the returned state visibly shows the result. If it is unchanged\nor only intermediate, try another approach. Respond only when the requested state\nis visibly present, or explain a concrete blocker you cannot resolve.\n\n## Tool surface\n\n`agent.computerUse.computer.\u003Ctool>(args)` is the low-level surface. Prefer the\nbound-object API above; reach for a tool only for what the API does not\nexpress — window enumeration, key repeat, or reading state back in the same\ncall. Arguments are strict: an undeclared key is refused. Each tool takes **one**\narguments object — the names below are its keys, not positional parameters:\n`get_app_state({ app_ref: { bundle_id: \"com.apple.Notes\" }, include_screenshot: true })`.\n\nName an app as the OS lists it (Windows: the Start-menu name, not a window title).\nNothing takes the user's focus, except on Windows: launching a non-packaged app\ndoes, and `include_screenshot=true` un-minimizes — a minimized tree is fully\nusable, so keep the default.\n\n```\nlist_apps({})\nlist_windows({app_ref})\nget_app_state({app_ref, include_screenshot?=false, disable_diffing?=false})\n\nleft_click({target, mouse_button?=\"left\", click_count?=1, modifiers?=\"\",\n           strategy?, app_ref?, return_state?})\nleft_click_drag({from_target, to, modifiers?=\"\", strategy?, app_ref?,\n                return_state?})\nscroll({target, scroll_direction, scroll_amount, strategy?, app_ref?,\n       return_state?})\n\ntype({text, target?, app_ref?, strategy?, return_state?})\nset_value({target, value, strategy?, app_ref?, return_state?})\nselect_text({target, text_range?, app_ref?, return_state?})\nkey({text, repeat?, hold_seconds?, app_ref?, strategy?, return_state?})\npaste({text, format?=\"text\", app_ref?, return_state?})\nperform_action({target, action, app_ref?, return_state?})\n\nrequest_access({capabilities?})\nstop_computer_control({reason?})\n```\n\nArgument shapes: `app_ref` \u002F `app` is an `AppRef`, but a bare string here is\nread as a bundle id, so pass `{name: \"Notes\"}` for a display name.\n`scroll_direction` is `up|down|left|right`, `scroll_amount` is pages, `strategy`\nis `auto|a11y|event`, and `return_state` is `compact|full|none` to return the app\nstate in the same call. For `target`, `text_range`, `modifiers` and the response\nshapes, see `nodeRepl.write(await agent.documentation.get(\"computer-use\"))`.\n",{"name":5,"description":7},"main","fec975905a2abd4c07e35c40d51fa097a2258ec9","apps\u002Fzcode-cli\u002Fpackages\u002Fzcode-cua-plugin\u002Fskills\u002Fcomputer-use",2710,"https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode","https:\u002F\u002Fzcode.z.ai\u002F","https:\u002F\u002Fgithub.com\u002Fzai-org","https:\u002F\u002Fwww.zhipuai.cn\u002Fen","ChatGLM, GLM-4.5, CogVLM, CodeGeeX, CogView, CogVideoX | CogDL, AMiner | Zhipu.ai (Z.ai)","2026-11-13 16:21:40",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add zai-org\u002FZCode --skill computer-use",{"tool":40,"command":41},"bunx","bunx skills add zai-org\u002FZCode --skill computer-use",{"tool":43,"command":44},"pnpm","pnpm dlx skills add zai-org\u002FZCode --skill computer-use","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fapps\u002Fzcode-cli\u002Fpackages\u002Fzcode-cua-plugin\u002Fskills\u002Fcomputer-use\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7D57RTFKZH4SFFWF6NXSQ62","plugin-mcp-ping","E2E workspace Plugin skill marker","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Fplugin-mcp-skill\u002Fe2e-plugin-mcp-ping\u002Fskills\u002Fplugin-mcp-ping\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7D57NRW93T0ETX2QPQY3JCP","e2e-ext-compat-plain","PLM-EXT-STORE fixture skill for e2e-ext-compat-plain.","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Ffs\u002Fplugins\u002Fplugin-store-extension-compat\u002Fstore-market\u002Fplugins\u002Fe2e-ext-compat-plain\u002Fskills\u002Fe2e-ext-compat-plain\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7D57JYKJK5A4VW7Y5MYEA7R","e2e-ext-compat-ok","PLM-EXT-STORE fixture skill for e2e-ext-compat-ok.","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Ffs\u002Fplugins\u002Fplugin-store-extension-compat\u002Fstore-market\u002Fplugins\u002Fe2e-ext-compat-ok\u002Fskills\u002Fe2e-ext-compat-ok\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7D57FZQKN28QJJ0HVG93ACN","e2e-ext-compat-installed","PLM-EXT-STORE fixture skill for e2e-ext-compat-installed.","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Ffs\u002Fplugins\u002Fplugin-store-extension-compat\u002Fstore-market\u002Fplugins\u002Fe2e-ext-compat-installed\u002Fskills\u002Fe2e-ext-compat-installed\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"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},"01M7D57C9W30WJ3NJDAYX2MN0J","e2e-ext-compat-future","PLM-EXT-STORE fixture skill for e2e-ext-compat-future.","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Ffs\u002Fplugins\u002Fplugin-store-extension-compat\u002Fstore-market\u002Fplugins\u002Fe2e-ext-compat-future\u002Fskills\u002Fe2e-ext-compat-future\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},"01M7D579KKRR6D2GPVW4J4QWVT","e2e-store-skill-b","E2E store fixture skill b","https:\u002F\u002Fgithub.com\u002Fzai-org\u002FZCode\u002Fblob\u002Fmain\u002Fpackages\u002Fdesktop\u002Ftest\u002Fe2e\u002Ffixtures\u002Ffs\u002Fplugins\u002Fplugin-extension-reads\u002Fstore-market\u002Fplugins\u002Fe2e-ext-store-b\u002Fskills\u002Fe2e-store-skill-b\u002FSKILL.md",[],[]]