Skip to content
Back to search

clawdcursor

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/AmrDab/clawdcursor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/AmrDab/clawdcursor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amrdab--clawdcursor/badge.svg)](/listings/amrdab--clawdcursor)

HTML

<a href="/listings/amrdab--clawdcursor"><img src="/api/listings/amrdab--clawdcursor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pick your host. Each one needs the one-time desktop-control consent, and on macOS the Accessibility and Screen Recording permissions ([macOS setup](docs/MACOS-SETUP.md)).

Claude Code: the plugin

claude plugin marketplace add AmrDab/clawdcursor
claude plugin install clawdcursor@clawdcursor

The plugin registers the MCP server (through `npx`, so no separate install; Node.js 20+ required) and bundles the usage skill. The first tool call asks "Allow clawdcursor to control this computer" in the app.

Claude Desktop: the .mcpb extension

Download the extension for your OS from the [latest GitHub release](https://github.com/AmrDab/clawdcursor/releases/latest) and open it:

| Windows | macOS | Linux | |---|---|---| | [clawdcursor-win32.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-win32.mcpb) | [clawdcursor-darwin.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-darwin.mcpb) | [clawdcursor-linux.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-linux.mcpb) |

1. Double-click the file, or use **Settings → Extensions → Advanced settings → Install Extension…**. 2. Turn on **Allow clawdcursor to control this computer**. That is the consent; until it is on, every tool returns a consent prompt. 3. **macOS:** when asked, allow Claude under **Privacy & Security → Accessibility** and **Screen Recording**.

No Node.js, npm or JSON editing: Claude Desktop runs the bundled server.

Codex, Cursor and other MCP hosts: `clawdcursor mcp --compact`

Install once:

npm i -g clawdcursor            # Node.js 20+
clawdcursor consent --accept    # one-time desktop-control consent
clawdcursor grant               # macOS only: Accessibility + Screen Recording

Then register a stdio server whose command is `clawdcursor mcp --compact`. The host starts it; you never run it yourself. Only the config shape differs:

**OpenAI Codex** (`~/.codex/config.toml`; the first launch can take a few seconds, so raise the 10 s startup timeout):

[mcp_servers.clawdcursor]
command = "clawdcursor"
args = ["mcp", "--compact"]
startup_timeout_sec = 30

**Cursor, Windsurf, Cline, Gemini CLI, Claude Desktop without the extension** (`mcpServers`):

{
  "mcpServers": {
    "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  }
}

**VS Code (Copilot)** (`.vscode/mcp.json` uses `servers`, not `mcpServers`):

{
  "servers": {
    "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  }
}

**Zed** (`context_servers` in `settings.json`):

{
  "context_servers": {
    "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  }
}

**opencode** (`opencode.json` uses `mcp`, and `command` is an array):

{
  "mcp": {
    "clawdcursor": { "type": "local", "command": ["clawdcursor", "mcp", "--compact"] }
  }
}

**Claude Code without the plugin:**

claude mcp add clawdcursor -s user -- clawdcursor mcp --compact

One-click for Cursor and VS Code (these use `npx`, no global install):

Notes:

- **No global install:** use `npx` as the command with args `-y clawdcursor mcp --compact`. A global install is still the better choice for a tool with desktop control: the version is pinned and on disk, and on macOS the native helper is built at install time. - **Windows:** some hosts start the server without a shell and cannot find `clawdcursor` or `npx` (both are `.cmd` shims). If the server does not start, wrap it: `"command": "cmd", "args": ["/c", "clawdcursor", "mcp", "--compact"]`. - **Consent in the app:** hosts that support MCP elicitation (Claude Code, VS Code) ask for consent on the first tool call, so `consent --accept` can be skipped there.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines
  1. {
  2. "name": "clawdcursor",
  3. "owner": {
  4. "name": "Amr Dabbas",
  5. "url": "https://github.com/AmrDab"
  6. },
  7. "metadata": {
  8. "description": "Cross-OS desktop & browser control for AI agents, through the accessibility tree first and screenshots last — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "clawdcursor",
  14. "source": "./",
  15. "description": "Cross-OS desktop & browser control, through the accessibility tree first and screenshots last — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available. Registers the clawdcursor MCP server (compact tool surface) and bundles its usage skill. Launches via npx, so no separate install step is required.",
  16. "version": "2.1.0",
  17. "homepage": "https://clawdcursor.com",
  18. "license": "MIT",
  19. "keywords": [
  20. "mcp",
  21. "desktop-automation",
  22. "computer-use",
  23. "gui-automation",
  24. "accessibility",
  25. "fallback"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 502 lines · 2 findings marked
  1. <h1 align="center">Clawd Cursor</h1>
  2. <p align="center">
  3. <strong>Lets AI use your computer in real time.</strong><br>
  4. clawdcursor picks the fastest way into each app: the page itself in browsers, the accessibility tree in desktop apps, text recognition when there's no tree, and screenshots last. After every action it tells your AI whether it worked.
  5. </p>
  6. <p align="center">
  7. <a href="LICENSE"><img src="https://img.shields.io/github/license/AmrDab/clawdcursor?color=a855f7" alt="MIT license"></a>
  8. <a href="https://github.com/AmrDab/clawdcursor/releases/latest"><img src="https://img.shields.io/github/v/release/AmrDab/clawdcursor?color=22c55e&label=release" alt="Latest release"></a>
  9. <a href="https://www.npmjs.com/package/clawdcursor"><img src="https://img.shields.io/npm/v/clawdcursor?color=cb3837&logo=npm" alt="npm"></a>
  10. <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?logo=nodedotjs&logoColor=white" alt="Node 20+">
  11. <img src="https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-0ea5e9" alt="Cross-platform">
  12. <a href="https://glama.ai/mcp/servers/AmrDab/clawdcursor"><img src="https://glama.ai/mcp/servers/AmrDab/clawdcursor/badges/score.svg" alt="clawdcursor MCP server on Glama" height="20"></a>
  13. <a href="https://github.com/AmrDab/clawdcursor/actions/workflows/cross-platform.yml"><img src="https://img.shields.io/github/actions/workflow/status/AmrDab/clawdcursor/cross-platform.yml?branch=main&label=tests" alt="Tests"></a>
  14. <a href="https://discord.gg/hW29nrEZ8G"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  15. </p>
  16. <p align="center">
  17. <a href="#what-it-does">What it does</a> &middot;
  18. <a href="#proof">Proof</a> &middot;
  19. <a href="#how-it-works">How it works</a> &middot;
  20. <a href="#limits">Limits</a> &middot;
  21. <a href="#what-protects-you">What protects you</a> &middot;
  22. <a href="#error-reports">Error reports</a> &middot;
  23. <a href="#install">Install</a> &middot;
  24. <a href="CHANGELOG.md">Changelog</a>
  25. </p>
  26. ---
  27. ## What it does
  28. Clawd Cursor is a free, open-source (MIT) MCP server. Your AI (Claude, Codex, Cursor, a local model, any MCP client) connects to it and gets six tools to use a real Windows, macOS or Linux computer: `accessibility`, `system`, `window`, `browser`, `computer` and `batch`.
  29. It sees the parts of an app by name, through the same data screen readers use: "Email field", "Confirm button". Your AI acts on those parts by name: type into Email, press Confirm, choose High. After each change Clawd Cursor reads the result back and reports `confirmed`, `unverified` or `failed`. Text is read exactly.
  30. Clawd Cursor has no model and no API key of its own: your AI makes every decision. Use it for the steps that only exist in a GUI. If an API, a command-line tool or a file edit does the job, use that instead.
  31. ---
  32. ## Proof
  33. Our own benchmark: the Codex agent on Windows, 15 tasks.
  34. | Measure | Result |
  35. |---|---|
  36. | Tasks done | 14 of 15 |
  37. | Acted by name | about 100% where the app has an accessibility tree |
  38. | Within the call budget | 12 of 15 |
  39. | Screenshots | 4 in total, all on the two drawing-canvas tasks (the fewest those tasks allow) |
  40. | Loops | 0 |
  41. | False "ok" | 1 found (an action reported as done that was not): fixed on main, ships in the next release |
  42. The scope is narrow: one OS, one agent, 15 tasks we built for the test. macOS, Linux and other models are not measured yet. From 2.1 the same benchmark runs on all three systems with several models, and a release ships only when it passes. How it measures: [bench/README.md](bench/README.md).
  43. ---
  44. ## How it works
  45. Your AI tries these in order and uses the first that works. Your AI makes every decision; Clawd Cursor carries it out and checks it.
  46. 1. **The page itself, in Clawd Cursor's own browser window.** `browser navigate` opens Chrome or Edge with its own profile and connects to it through Playwright; your AI then reads and clicks the page from the inside. A page already open in your own browser is read through the accessibility tree.
  47. 2. **The accessibility tree, in desktop apps and your own browser.** Apps list their buttons, fields and menus by name for screen readers. Clawd Cursor reads that list and acts on each part by name.
  48. 3. **Text recognition (OCR), when there is no tree.** It reads the words on the screen and can click a visible label.
  49. 4. **Screenshots, last.** Only when nothing else works, such as on drawing canvases and 3D views.
  50. After every action the result ends with one status line: `confirmed` (it saw the change), `unverified` (nothing could check it), `refused` (a protection stopped it) or `failed` (with a code and the next call to try). Pass `expect` on an action that matters: the call re-reads the screen and reports a `DEVIATION` if the expected state is not there.
  51. ```mermaid
  52. flowchart TB
  53. agent["Your AI (in its host)<br/>plans · chooses tools · checks results"] --> see{"SEE: the fastest way in first"}
  54. see -- "own browser window" --> page["browser navigate, then read_text<br/>the web page itself, through Playwright"]
  55. see -- "desktop app or your browser" --> tree["accessibility read_tree · system copy_all_text<br/>element names, positions, exact text"]
  56. see -- "no tree" --> ocr["system ocr<br/>the words on screen"]
  57. see -- "last" --> shot["computer screenshot<br/>sends an image to the model"]
  58. page --> act
  59. tree --> act
  60. ocr --> act
  61. shot --> act
  62. act["ACT: by name first<br/>invoke · set_value · smart_click · then click x,y"] --> guards
  63. guards["Always checked<br/>Stop · pause · AI-assistant window · hard key list"] -- ok --> desktop["Real desktop"]
  64. guards -- refused --> refused["refused, with a reason"]
  65. desktop --> result["Result line<br/>confirmed · unverified · refused · failed"]
  66. result --> agent
  67. ```
  68. In tool terms:
  69. - **See.** `accessibility read_tree` lists a window's parts by name, `system copy_all_text` gives the exact text of a page or document, and `system ocr` reads the screen when the tree is empty. `computer screenshot` and its variants (`screenshot_region`, `zoom`) come last: they are the only reads that put an image in the model's context. On a page your AI opened with `browser navigate`, `browser read_text` reads the page itself.
  70. - **Act.** `accessibility invoke` clicks a part by name and `set_value` fills a field. If the name is not in the tree, `smart_click` finds the visible label by OCR. `compile_ui`, `find_button` and `find_field` return an `{element_id, snapshot_id}` pair that stays valid when the layout shifts. A click at a screen position is for a target with no name and no visible text.
  71. - **Keys.** The server tells your AI which OS it is on. `mod` means `cmd` on macOS and `ctrl` on Windows and Linux.
  72. ### The words, in plain terms
  73. - **MCP** (Model Context Protocol): the standard way to plug tools into an AI app. Clawd Cursor is the tool side; your AI app connects to it.
  74. - **Accessibility tree:** the list of buttons, fields and menus an app gives the system, each with a name. Screen readers for blind people use the same list.
  75. - **Acting by name:** pressing "Send" because it is called Send, not because it sits at a spot on the screen.
  76. - **OCR:** text recognition, reading the words in a picture of the screen. It runs on your computer.
  77. - **Playwright and CDP:** Playwright is a library that controls Chrome and Edge from the inside, over the Chrome DevTools Protocol (CDP), the browser's own debugging connection. Apps built on a browser engine (Electron or WebView2) can be reached the same way; `system detect_webview` finds them.
  78. - **Compact tools:** the six tools your AI sees with `--compact`. Without it there are 89 smaller tools, one per action. See [The tools](#the-tools).
  79. - **The pill and the outline:** while your AI is working, a pill on screen says what it is doing ("Typing in Edge") and a thin amber outline marks the window it is working in, moving with it from window to window; it turns blue while your AI waits for you. Clicks go through it, and it stays out of your AI's screenshots.
  80. ---
  81. ## Limits
  82. - It depends on apps exposing accessibility info. Most do: web pages, native apps, Office and system dialogs.
  83. - Apps that draw their own screen (drawing canvases, games, CAD viewports) have no named parts. There it needs OCR or screenshots.
  84. - The benchmark covers Windows and one agent so far. macOS and Linux are supported but not benchmarked yet.
  85. - It acts with your permissions, and it has no built-in policy engine: see [What protects you](#what-protects-you).
  86. ---
  87. ## What protects you
  88. Clawd Cursor runs with **your own OS permissions**: anything you can do with a mouse and a keyboard, your AI can do through it.
  89. What is enforced, whatever your AI sends:
  90. - **A Stop button.** Press Stop on the pill (or double-click it), or run `clawdcursor stop`. Every Clawd Cursor process stops, including a call or batch already running, and stays stopped across restarts until you resume.
  91. - **The pause card.** For a sign-in or a 2FA code your AI hands that one step to you with `system pause_for_user`: a card on screen says what is needed and can offer choices or a text box, and your AI continues when you click Resume, or as soon as its `done_when` condition shows on screen. While the card is up, no other tool call runs. A choice or a typed reply on the card comes only from you: your AI cannot click its own card or the pill. On the granular surface an agent can also end a pause with `resume_task`; that is reported as unverified, never as your answer.
  92. - **No typing into AI assistant windows.** Input is refused when the window in front is an AI assistant your AI did not focus or open on purpose, or is no longer the window it was working in.
  93. - **Password values are never read.** Password field values are never returned by tree, find or value reads on Windows, macOS and Linux. A screenshot or OCR can still show whatever is visible on screen.
  94. - **A short list of keys that are never sent**, because they lock the machine or end the session. Windows: `Win+L`, `Ctrl+Alt+Del`. macOS: `Ctrl+Cmd+Q`, `Cmd+Shift+Q`, anything with Power or Eject. Linux: `Super+L`, `Ctrl+Alt+Del`, `Ctrl+Alt+Backspace`, `Ctrl+Alt+F1`&ndash;`F12`, SysRq, Power. Every other shortcut is allowed.
  95. - **Local only, with a token.** `clawdcursor agent` binds `127.0.0.1` only and requires the bearer token. `clawdcursor mcp` (stdio) opens no port.
  96. - **Screen text is marked as data.** Page text, OCR, the clipboard, titles and element names reach your AI inside `<untrusted-screen-content>` or quoted, and cannot break out of that wrapping. Whether the model obeys text it reads is the model's and the host's side of prompt-injection defence.
  97. - **One-time consent.** No tool runs until you accept once.
  98. What is not enforced by Clawd Cursor:
  99. - **There is no built-in policy engine.** Clawd Cursor does not decide which actions your AI may take, and nothing is refused for being "destructive". Your AI and your MCP host's approval prompts decide. (The policy gate of 1.x was removed in 2.0 because a click by coordinates went around it.)
  100. - **Per-action approval is your host's job.** The tools carry `readOnlyHint` / `destructiveHint` annotations for hosts that prompt. Approving a Clawd Cursor tool in a host means approving desktop control with your rights, not one narrow action. On the compact surface all six tools are marked destructive, because each covers many actions; the granular surface has one hint per action.
  101. - **If your host auto-approves tool calls, nothing asks before an irreversible action.** Your AI is instructed to ask on the pause card before sending, deleting, paying or closing unsaved work that you did not ask for, but that is an instruction, not a check. For agents you do not fully trust, or for unattended runs, use a host with approval prompts, or, from 2.1, turn on confirm mode ([#373](https://github.com/AmrDab/clawdcursor/issues/373)): with `CLAWD_CONFIRM=1` in the server's environment (in the Claude Desktop extension, the "Ask before Send / Delete / Pay / Close" setting), a click or key that would send, delete, pay or close waits on the pause card until you click Resume. Its limits are in [SECURITY.md](SECURITY.md).
  102. - **An agent with its own shell** on your machine is not confined by Clawd Cursor at all.
  103. Privacy:
  104. - **No model calls.** Screenshots and screen text go only to the MCP client that asked for them. `clawdcursor report` is opt-in and previews what it sends. For the error reports that start in 2.1, see [Error reports](#error-reports).
  105. - **No screenshots, if you want.** `clawdcursor agent --no-vision`, or `CLAWD_DISABLE_VISION=1` (which also covers stdio), refuses every call that would return an image; your AI works from the accessibility tree and OCR text.
  106. - **Logs.** `~/.clawdcursor/logs/` records which tool ran and whether it worked, not typed text or screen content.
  107. - **Pauses.** A pause times out after 15 minutes (`CLAWD_PAUSE_TIMEOUT_MIN`). `CLAWD_NO_PAUSE=1` turns pausing off for CI and unattended runs.
  108. [SECURITY.md](SECURITY.md) has the threat model, the limits of each guarantee, and how to report a vulnerability privately.
  109. ---
  110. ## Error reports
  111. 2.0.0 sent nothing. **From 2.1**, Clawd Cursor sends anonymous error reports by default, so bugs get found and fixed. Every value is a number or comes from a fixed list, and tool and action names are Clawd Cursor's own.
  112. - **With every report:** a random install id made on your computer (not derived from your hardware or accounts), the Clawd Cursor version and your OS family.
  113. - **`start`, when the server starts:** OS major version, CPU architecture, Node.js major version, which AI app started it (from a fixed list: Claude Code, Claude Desktop, Cursor, Codex and others; anything else is "other"), and compact or granular tools.
  114. - **`call_failed`, when a call fails, times out or reads nothing:** the tool and action name, the result code (`NOT_FOUND`, `TIMEOUT`, ...), the outcome, how long it took, and whether the app was a browser, an Electron app or a native app.
  115. - **`slow_call`, when a call takes over 10 seconds:** the tool and action name, how long it took, and its slow internal steps (Clawd Cursor's own helper programs, by name, with their time).
  116. - **`exit`, when the server exits during a call, or was killed or crashed:** the exit reason (from a fixed list: `sigterm`, `host_gone`, ...), and the tool and action that were cut off and how long they had run.
  117. - **`crash`, on an uncaught error:** the error class (`TypeError`, ...), the error code (`ENOENT`, ...), and the stack reduced to file and line in Clawd Cursor's own code.
  118. - **Never sent:** error messages, typed text, the clipboard, screen or OCR text, screenshots, window titles, the names of the apps your AI works in, URLs, element names, file paths outside Clawd Cursor, user names, emails or IP addresses.
  119. - **Where it goes:** over HTTPS to `telemetry.clawdcursor.com`, a Cloudflare Worker run by the project. It checks every event against the same fixed lists and drops anything else, does not read or store your IP address or request headers, and deletes events after 90 days.
  120. - **To turn them off:** run `clawdcursor optout` (`clawdcursor optin` turns them back on), ask your AI (it calls `system {action:"telemetry_optout"}`; your AI can only turn them off), or set `CLAWD_TELEMETRY=0` or `DO_NOT_TRACK=1`. They are always off in CI and in test runs.
  121. From 2.1, `clawdcursor telemetry` prints the status and every field it sends. The same list is in [docs/telemetry.md](docs/telemetry.md).
  122. ---
  123. ## Install
  124. Pick your host. Each one needs the one-time desktop-control consent, and on macOS the Accessibility and Screen Recording permissions ([macOS setup](docs/MACOS-SETUP.md)).
  125. ### Claude Code: the plugin
  126. ```bash
  127. claude plugin marketplace add AmrDab/clawdcursor
  128. claude plugin install clawdcursor@clawdcursor
  129. ```
  130. The plugin registers the MCP server (through `npx`, so no separate install; Node.js 20+ required) and bundles the usage skill. The first tool call asks "Allow clawdcursor to control this computer" in the app.
  131. ### Claude Desktop: the .mcpb extension
  132. Download the extension for your OS from the [latest GitHub release](https://github.com/AmrDab/clawdcursor/releases/latest) and open it:
  133. | Windows | macOS | Linux |
  134. |---|---|---|
  135. | [clawdcursor-win32.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-win32.mcpb) | [clawdcursor-darwin.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-darwin.mcpb) | [clawdcursor-linux.mcpb](https://github.com/AmrDab/clawdcursor/releases/latest/download/clawdcursor-linux.mcpb) |
  136. 1. Double-click the file, or use **Settings → Extensions → Advanced settings → Install Extension…**.
  137. 2. Turn on **Allow clawdcursor to control this computer**. That is the consent; until it is on, every tool returns a consent prompt.
  138. 3. **macOS:** when asked, allow Claude under **Privacy & Security → Accessibility** and **Screen Recording**.
  139. No Node.js, npm or JSON editing: Claude Desktop runs the bundled server.
  140. ### Codex, Cursor and other MCP hosts: `clawdcursor mcp --compact`
  141. Install once:
  142. ```bash
  143. npm i -g clawdcursor # Node.js 20+
  144. clawdcursor consent --accept # one-time desktop-control consent
  145. clawdcursor grant # macOS only: Accessibility + Screen Recording
  146. ```
  147. Then register a stdio server whose command is `clawdcursor mcp --compact`. The host starts it; you never run it yourself. Only the config shape differs:
  148. **OpenAI Codex** (`~/.codex/config.toml`; the first launch can take a few seconds, so raise the 10 s startup timeout):
  149. ```toml
  150. [mcp_servers.clawdcursor]
  151. command = "clawdcursor"
  152. args = ["mcp", "--compact"]
  153. startup_timeout_sec = 30
  154. ```
  155. **Cursor, Windsurf, Cline, Gemini CLI, Claude Desktop without the extension** (`mcpServers`):
  156. ```json
  157. {
  158. "mcpServers": {
  159. "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  160. }
  161. }
  162. ```
  163. **VS Code (Copilot)** (`.vscode/mcp.json` uses `servers`, not `mcpServers`):
  164. ```json
  165. {
  166. "servers": {
  167. "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  168. }
  169. }
  170. ```
  171. **Zed** (`context_servers` in `settings.json`):
  172. ```json
  173. {
  174. "context_servers": {
  175. "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
  176. }
  177. }
  178. ```
  179. **opencode** (`opencode.json` uses `mcp`, and `command` is an array):
  180. ```json
  181. {
  182. "mcp": {
  183. "clawdcursor": { "type": "local", "command": ["clawdcursor", "mcp", "--compact"] }
  184. }
  185. }
  186. ```
  187. **Claude Code without the plugin:**
  188. ```bash
  189. claude mcp add clawdcursor -s user -- clawdcursor mcp --compact
  190. ```
  191. One-click for Cursor and VS Code (these use `npx`, no global install):
  192. [![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-0ea5e9?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=clawdcursor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsYXdkY3Vyc29yIiwibWNwIiwiLS1jb21wYWN0Il19)
  193. [![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=clawdcursor&config=%7B%22name%22%3A%22clawdcursor%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22clawdcursor%22%2C%22mcp%22%2C%22--compact%22%5D%7D)
  194. Notes:
  195. - **No global install:** use `npx` as the command with args `-y clawdcursor mcp --compact`. A global install is still the better choice for a tool with desktop control: the version is pinned and on disk, and on macOS the native helper is built at install time.
  196. - **Windows:** some hosts start the server without a shell and cannot find `clawdcursor` or `npx` (both are `.cmd` shims). If the server does not start, wrap it: `"command": "cmd", "args": ["/c", "clawdcursor", "mcp", "--compact"]`.
  197. - **Consent in the app:** hosts that support MCP elicitation (Claude Code, VS Code) ask for consent on the first tool call, so `consent --accept` can be skipped there.
  198. - **Per-OS requirements.** Windows: none. macOS: Xcode Command Line Tools (`xcode-select --install`) to build the native helper. Linux: `tesseract-ocr` (OCR), `python3-gi` and `gir1.2-atspi-2.0` (accessibility tree), and on Wayland `ydotool`.
  199. - **Permission allowlists:** use the server-level wildcard `mcp__clawdcursor`, not per-tool entries.
  200. <details>
  201. <summary>Installer scripts (they run <code>npm i -g clawdcursor</code> after checking Node and PATH)</summary>
  202. ```powershell
  203. # Windows (PowerShell)
  204. powershell -c "irm https://clawdcursor.com/install.ps1 | iex"
  205. ```
  206. ```bash
  207. # macOS / Linux
  208. curl -fsSL https://clawdcursor.com/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 280 on GitHub
  209. ```
  210. </details>
  211. ### Over HTTP: `clawdcursor agent`
  212. For an agent that speaks MCP over HTTP (a headless process, the Agent SDK, your own loop):
  213. ```bash
  214. clawdcursor agent --compact # HTTP MCP on 127.0.0.1:3847/mcp
  215. ```
  216. Every request needs the bearer token in `~/.clawdcursor/token`. The server binds to `127.0.0.1` only; to reach it from another machine, tunnel the port over SSH (`ssh -L 3847:127.0.0.1:3847 user@host`). Use the daemon's own port on your side too: the server answers only requests addressed to `127.0.0.1:<its port>` or `localhost:<its port>`, so a tunnel from another local port gets 403.
  217. ```bash
  218. # List the tools. The Accept header is required by MCP's Streamable HTTP transport.
  219. curl -s -X POST http://127.0.0.1:3847/mcp \
  220. -H "Authorization: Bearer $(cat ~/.clawdcursor/token)" \
  221. -H "Content-Type: application/json" \
  222. -H "Accept: application/json, text/event-stream" \
  223. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  224. ```
  225. ```powershell
  226. # Windows PowerShell 5.1
  227. $token = (Get-Content "$env:USERPROFILE\.clawdcursor\token" -Raw).Trim()
  228. $headers = @{ Authorization = "Bearer $token"; Accept = "application/json, text/event-stream" }
  229. $body = '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  230. Invoke-RestMethod -Method Post -Uri http://127.0.0.1:3847/mcp -Headers $headers -ContentType "application/json" -Body $body
  231. ```
  232. ### Updating
  233. | Installed as | Update with |
  234. |---|---|
  235. | Global npm package | `npm i -g clawdcursor@latest` |
  236. | Claude Desktop extension | Download the new `.mcpb` from the [latest release](https://github.com/AmrDab/clawdcursor/releases/latest) and open it |
  237. | Claude Code plugin | `claude plugin marketplace update clawdcursor`, then `claude plugin update clawdcursor@clawdcursor` |
  238. Restart the host afterwards so it starts the new server. `clawdcursor versions` lists every copy on the machine and its version. From 2.1, `clawdcursor update` updates the global npm package and lists the other copies that need their own update.
  239. **Coming from 1.x:** remove calls to the `task` tool and to `clawdcursor task`, drop the `--provider`, `--model`, `--base-url` and `--api-key` flags and the `AI_API_KEY` / `CLAWD_*_MODEL` variables, and configure the model in your agent host. Old config files still load; the model keys in them are ignored.
  240. ---
  241. ## What's new
  242. **2.0.0** &mdash; **A tool, driven by your agent.** First published as 1.6.0 and renumbered because it is a breaking change; 1.6.0 is deprecated on npm. ([full changelog](CHANGELOG.md))
  243. - **Breaking:** the built-in agent loop and all model settings are gone. The `task` tool, `clawdcursor task`, the scheduler and the `--provider` / `--model` / `--api-key` flags are removed, and `clawdcursor doctor` is a diagnostic only. Your agent calls the six tools step by step, or `batch` for a known sequence.
  244. - **Breaking:** the policy gate is gone: no tiers, no "confirm", nothing refused by label. See [What protects you](#what-protects-you) for what is still enforced, and what is not.
  245. - A thin outline around the window the agent is working in replaces the full-screen glow.
  246. - Keys follow the OS: the agent is told its modifier (`cmd` or `ctrl`) up front, `mod` means that modifier, and shortcuts are offered only for this OS.
  247. - Screen text that reaches the agent cannot close its `<untrusted-screen-content>` block, and `open_app` only starts an installed app by name.
  248. **1.5.27** &mdash; Ticks, dropdowns and expanders read and change the same way on all three OSes; a stop also blocks hover, clipboard writes, page script and tab switches; logs in `~/.clawdcursor/logs/` record each call's timing and outcome without typed text or window titles.
  249. Earlier releases are in the [changelog](CHANGELOG.md).
  250. **2.1.** One standard benchmark across app types, OSes and models becomes the release gate, with five general mechanisms behind it: honest results, target resolution, perception without a tree, screen geometry and timing. The first three are in 2.1, and so are an opt-in confirm mode ([#373](https://github.com/AmrDab/clawdcursor/issues/373)), `clawdcursor update`, anonymous error reports and an orb in the pill; the thin outline around the agent's window stays as in 2.0. Screen geometry and timing are next: see the [2.1 milestone](https://github.com/AmrDab/clawdcursor/milestone/1).
  251. ---
  252. ## The tools
  253. Two surfaces run the same code behind the same guards.
  254. - **Compact** (`--compact`, recommended): six tools, each with an `action` parameter. About 7,000 tokens of `tools/list`.
  255. - **Granular** (the default without `--compact`): 89 tools, one per action. About 19,000 tokens. Use it when a runtime needs every primitive as its own tool, or when you want your host to prompt per kind of action.
  256. (Token figures are the `tools/list` JSON of 2.0.0, characters ÷ 3.5.)
  257. | Tool | Actions |
  258. |---|---|
  259. | `accessibility` | `read_tree`, `find`, `get_element`, `focused`, `invoke`, `focus`, `set_value`, `get_value`, `expand`, `collapse`, `toggle`, `select`, `state`, `list_children`, `wait_for`, `compile_ui`, `find_button`, `find_field`, `smart_click`, `smart_type`, `smart_read` |
  260. | `system` | `clipboard_read`, `clipboard_write`, `copy_all_text`, `report`, `system_time`, `ocr`, `undo`, `shortcuts_list`, `shortcuts_run`, `pause_for_user`, `detect_webview`, `relaunch_with_cdp`, `build_uri`, `open_uri`, `open_app`, `open_file`, `open_url` |
  261. | `window` | `list`, `active`, `focus`, `maximize`, `minimize`, `restore`, `close`, `resize`, `list_displays`, `screen_size`, `open_app`, `open_file`, `open_url`, `switch_tab`, `navigate` |
  262. | `browser` | `navigate`, `connect`, `page_context`, `read_text`, `click`, `type`, `select_option`, `evaluate`, `wait_for`, `list_tabs`, `switch_tab`, `scroll` |
  263. | `computer` | `click`, `double_click`, `right_click`, `middle_click`, `triple_click`, `hover`, `move`, `move_relative`, `scroll`, `scroll_horizontal`, `drag`, `drag_path`, `mouse_down`, `mouse_up`, `type`, `key`, `key_press`, `key_down`, `key_up`, `wait`, `screenshot`, `screenshot_region`, `zoom` |
  264. | `batch` | `{steps:[…]}`: several calls in one round trip. Each step is `{name, arguments, expect?}` and is refused exactly as a direct call would be; the batch halts with a per-step trace on a refusal, an error or a failed `expect`. |
  265. ```js
  266. accessibility({ action: "invoke", name: "Send" }) // click by name
  267. computer({ action: "key", combo: "mod+s" }) // Cmd+S on macOS, Ctrl+S elsewhere
  268. window({ action: "open_app", name: "Outlook" })
  269. ```
  270. The full guide for agents is [SKILL.md](SKILL.md); it ships in the npm package and the Claude Code plugin. [clawdcursor.com/llms.txt](https://clawdcursor.com/llms.txt) is a shorter summary of it: install, the tool surface and the safety rules. Every parameter is in [schema.snapshot.json](schema.snapshot.json).
  271. ---
  272. ## Platform support
  273. | Platform | UI tree | OCR | Browser (CDP) | Input |
  274. |---|---|---|---|---|
  275. | **Windows** 10/11 (x64 / ARM64) | UI Automation via a PowerShell bridge | `Windows.Media.Ocr` | Chrome / Edge | nut-js |
  276. | **macOS** 12+ (Intel / Apple Silicon) | Native AX helper (Swift), JXA fallback | Apple Vision | Chrome / Edge | nut-js + System Events |
  277. | **Linux** X11 | AT-SPI via `python3-gi` | Tesseract | Chrome / Edge | nut-js |
  278. | **Linux** Wayland | AT-SPI via `python3-gi` | Tesseract | Chrome / Edge | `ydotool` / `wtype` |
  279. - **Windows:** no setup.
  280. - **macOS:** Accessibility is required; Screen Recording is needed only for screenshots and OCR. `clawdcursor grant` opens the dialogs. See [docs/MACOS-SETUP.md](docs/MACOS-SETUP.md). Retina scaling is handled for you: do not pre-scale coordinates.
  281. - **Linux X11:** `sudo apt install tesseract-ocr python3-gi gir1.2-atspi-2.0`.
  282. - **Linux Wayland:** the same, plus `ydotool` with `ydotoold` (preferred) or `wtype` (keyboard only).
  283. ---
  284. ## CLI
  285. For people setting up or diagnosing an install. Agents connect over MCP. Start here:
  286. ```
  287. clawdcursor doctor Check the install and set it up
  288. clawdcursor agent Run clawdcursor, with a live log of every action on this computer
  289. clawdcursor task "<task>" Test an agent: it does <task> with clawdcursor as its only tool, then PASS or FAIL
  290. ```
  291. In a terminal, `clawdcursor agent` prints one line per action, whichever clawdcursor did it: the one your Claude app or
  292. editor started, a `clawdcursor task` run, or the daemon itself. Each line has the time, who did it (`agent` or
  293. `mcp <pid>`), the tool and action, the outcome (`ok`, `refused`, `failed`, ...) with its result code, and how long
  294. it took. A server connecting or leaving, a pause waiting for you, and a stop or resume get a line too. Names and codes
  295. only: no typed text, clipboard or screen text. Ctrl+C ends it. Run as a service or piped, it prints nothing extra.
  296. Every command:
  297. ```
  298. clawdcursor consent Desktop-control consent (--accept / --revoke / --status)
  299. clawdcursor grant Request macOS permissions (macOS only)
  300. clawdcursor mcp stdio MCP server; your host starts this (--compact for the six tools)
  301. clawdcursor agent HTTP MCP server on 127.0.0.1:3847, with the live log in a terminal (--port, --compact, --no-vision)
  302. clawdcursor stop Stop every running instance; agents stay stopped until resume
  303. clawdcursor resume Continue the daemon's paused task or give control back after a stop (--end to end the task)
  304. clawdcursor doctor Diagnose the install (version, consent, screen capture, accessibility, permissions)
  305. clawdcursor status Readiness check (consent, permissions, whether the daemon is running)
  306. clawdcursor versions Every installed copy and its version
  307. clawdcursor update Update the global npm install, then list the other copies to update (from 2.1)
  308. clawdcursor telemetry Whether error reports are on, and every field sent (from 2.1)
  309. clawdcursor optout Turn error reports off; optin turns them back on (from 2.1)
  310. clawdcursor report Send a redacted report of the last session, after a preview (--save-only)
  311. clawdcursor register-skill Register the usage skill in detected agents again
  312. clawdcursor uninstall Remove all config, data and skill registrations
  313. clawdcursor task "<task>" Developer add-on: a test agent with clawdcursor as its only tool (see below)
  314. clawdcursor logs Developer add-on: the logs, readably (-f, --session, --tool, --errors, --since, --run)
  315. ```
  316. `--no-banner` (or `CLAWD_NO_BANNER=1`) on `mcp` and `agent` turns the on-screen pill and outline off.
  317. ### Testing clawdcursor on its own
  318. For developers who want to see what an agent does when clawdcursor is the **only** tool it has. Optional: two small
  319. add-ons, downloaded from npm the first time you use them and only after you say yes.
  320. ```
  321. clawdcursor task "Open a text editor and type hello" # the agent does it, then PASS or FAIL
  322. clawdcursor logs --run last # that run, joined with clawdcursor's own log
  323. clawdcursor doctor --setup # pick the default runner and model, run a test call
  324. ```
  325. - **Your subscription, no API key.** `task` runs your installed Claude Code (`claude -p`) or Codex (`codex exec`) on
  326. your own sign-in. The agent gets one MCP server, this clawdcursor (`mcp --compact`, or `--granular`), and none of its
  327. built-in tools, settings, plugins or skills. `--with claude|codex` picks one; by default it is the one `doctor --setup`
  328. chose, else the installed and signed-in CLI, Claude Code first. `--model` names a model.
  329. - **API keys are optional:** `--with anthropic` (`ANTHROPIC_API_KEY`, or a key stored by `doctor --setup`) and
  330. `--with openai-compatible` (base URL, key and model: OpenAI, Ollama, LM Studio, OpenRouter) run a small tool-calling
  331. loop over the same MCP server.
  332. - **What you see:** each tool call with its action and a one-line result, and the agent's short messages. The agent
  333. ends with a `PASS: …` or `FAIL: …` line, and the exit code follows it: 0 PASS, 1 FAIL or error, 130 Ctrl-C (the agent
  334. and its clawdcursor are stopped).
  335. - **What is kept:** every event of the run in `~/.clawdcursor/runs/<time>.jsonl` (screenshots left out), with the id of
  336. the clawdcursor session it drove. `logs` shows the day log's tool calls with their outcome, result code and where the
  337. time went, and stop, pause, refusals and server start and exit; `--session last`, `--tool click`, `--errors`,
  338. `--since 10m`, `-f` narrow or follow it.
  339. - **The add-ons:** `clawdcursor-agent` (`task` and `logs`) and `clawdcursor-doctor` (`doctor --setup`), installed with
  340. `npm install --prefix ~/.clawdcursor/addons` at clawdcursor's own version. With no terminal to ask in, the command is
  341. printed and nothing is downloaded; `--yes` installs without asking (CI). `doctor --setup` stores an API key in
  342. `~/.clawdcursor/agent.json`, readable only by you, or just the name of the variable that holds it.
  343. ---
  344. ## Development
  345. ```bash
  346. git clone https://github.com/AmrDab/clawdcursor.git && cd clawdcursor
  347. npm install
  348. npm run build # tsc + postbuild + bundle -> dist/surface/cli.js
  349. npm test # vitest
  350. npm run lint # eslint
  351. npm link # global `clawdcursor` shim
  352. npm run build:addons # the developer add-ons in packages/
  353. CLAWDCURSOR_ADDONS_DIR=$PWD/packages clawdcursor task "..." # use them from the repo: nothing is downloaded
  354. ```
  355. | Directory | What lives here |
  356. |---|---|
  357. | `src/core/` | Reading the screen (accessibility snapshots, the UI compiler), verification, and the Stop / pause / AI-assistant guards. |
  358. | `src/tools/` | The granular tools, the five compound tools and `batch`. |
  359. | `src/platform/` | The `PlatformAdapter` for Windows, macOS, Linux and Wayland; OCR; the CDP driver; the hard key list. |
  360. | `src/surface/` | CLI, MCP server (stdio and HTTP), dashboard, doctor, consent. |
  361. | `packages/` | The optional developer add-ons: `clawdcursor-agent` (`task`, `logs`) and `clawdcursor-doctor` (`doctor --setup`). |
  362. CI runs the tests on Node 20 and 22 on Ubuntu, macOS and Windows, with a coverage threshold, a performance smoke test and an `npm audit` gate.
  363. ## Contributing
  364. See [CONTRIBUTING.md](CONTRIBUTING.md). Bugs and feature requests go in [issues](https://github.com/AmrDab/clawdcursor/issues); security reports go through [SECURITY.md](SECURITY.md).
  365. ## License
  366. MIT. See [LICENSE](LICENSE).
  367. ## Acknowledgments
  368. Built on the Model Context Protocol SDK, nut-js, Playwright, sharp, and the AT-SPI, UI Automation and AX accessibility APIs.
  369. The pill's orb follows **Thinking Orbs** by Jakub Antalik ([libraries.dev](https://libraries.dev), [github.com/Jakubantalik/Libraries.dev](https://github.com/Jakubantalik/Libraries.dev)), MIT License, Copyright (c) 2026 Jakub Antalik. Its values (orbits, sizes, timings) are used in `scripts/banner.ps1` and `scripts/mac/overlay.swift`; the full MIT notice is at the top of `scripts/banner.ps1`.
  370. ---
  371. <p align="center">
  372. <a href="https://clawdcursor.com">clawdcursor.com</a> &middot;
  373. <a href="https://discord.gg/hW29nrEZ8G">Discord</a> &middot;
  374. <a href="CHANGELOG.md">Changelog</a> &middot;
  375. <a href="https://www.npmjs.com/package/clawdcursor">npm</a>
  376. </p>
docs/install.ps1 · Bundled script · 130 lines · 2 findings marked
  1. # Clawd Cursor Installer for Windows
  2. # Usage: powershell -c "irm https://clawdcursor.com/install.ps1 | iex"
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 2 on GitHub
  3. # Specify version: $env:VERSION='v2.1.0'; irm https://clawdcursor.com/install.ps1 | iex
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 3 on GitHub
  4. #
  5. # Installs the published npm package globally (npm i -g clawdcursor) -- no git
  6. # clone, no local build toolchain. Windows needs no native build step.
  7. $ErrorActionPreference = "Continue"
  8. # VERSION maps to an npm dist-tag/version. The old git-branch default ("main")
  9. # and a leading "v" both normalise to npm's "latest"/"x.y.z" form.
  10. $VERSION = if ($env:VERSION) { $env:VERSION } else { "latest" }
  11. if ($VERSION -in @("main", "latest", "")) {
  12. $PKG = "clawdcursor@latest"; $DISPLAY_VERSION = "latest"
  13. } else {
  14. $clean = $VERSION -replace '^v', ''
  15. $PKG = "clawdcursor@$clean"; $DISPLAY_VERSION = $clean
  16. }
  17. Write-Host ""
  18. Write-Host " /\___/\" -ForegroundColor Green
  19. Write-Host " ( >^.^< ) Clawd Cursor Installer" -ForegroundColor Green
  20. Write-Host " ) (" -ForegroundColor Green
  21. Write-Host " (_)_(_)_)" -ForegroundColor Green
  22. Write-Host ""
  23. # ── 1. Check Node.js ─────────────────────────────────────────────────────────
  24. $nodeVersion = $null
  25. try { $nodeVersion = (node --version 2>$null) } catch {}
  26. if (-not $nodeVersion) {
  27. Write-Host " [X] Node.js not found. Get it from https://nodejs.org (v20+)" -ForegroundColor Red
  28. exit 1
  29. }
  30. $major = [int]($nodeVersion -replace 'v(\d+)\..*', '$1')
  31. if ($major -lt 20) {
  32. Write-Host " [X] Node.js $nodeVersion is too old. Update to v20+: https://nodejs.org" -ForegroundColor Red
  33. exit 1
  34. }
  35. Write-Host " [OK] Node.js $nodeVersion" -ForegroundColor Green
  36. # ── 2. Install from npm (updates an existing global copy in place) ───────────
  37. # The version already installed, so we can say "updated X -> Y" afterwards.
  38. $before = $null
  39. try {
  40. $ls = npm ls -g clawdcursor --depth=0 --json 2>$null | Out-String | ConvertFrom-Json
  41. $before = $ls.dependencies.clawdcursor.version
  42. } catch {}
  43. # Windows refuses to replace files a running process has open (EBUSY): an
  44. # editor or Claude session that has clawdcursor running blocks the update.
  45. # Only processes running from the global copy hold its files open.
  46. $globalDir = $null
  47. try { $globalDir = (Join-Path (npm prefix -g 2>$null).Trim() 'node_modules\clawdcursor').ToLower() } catch {}
  48. $running = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" -ErrorAction SilentlyContinue |
  49. Where-Object { $globalDir -and $_.CommandLine -and $_.CommandLine.Replace('/', '\').ToLower().Contains($globalDir) })
  50. if ($before -and $running.Count -gt 0) {
  51. Write-Host " [!] clawdcursor is running in $($running.Count) session(s) (your editor or Claude app)." -ForegroundColor Yellow
  52. Write-Host " If the update fails with EBUSY, close those sessions or run 'clawdcursor stop', then re-run this" -ForegroundColor Yellow
  53. Write-Host " (after a stop, run 'clawdcursor resume' to let agents act again)." -ForegroundColor Yellow
  54. }
  55. Write-Host " Installing $PKG (global)..." -ForegroundColor Cyan
  56. $output = npm install -g $PKG --loglevel error 2>&1 | Out-String
  57. if ($LASTEXITCODE -ne 0) {
  58. Write-Host " [X] npm install failed:" -ForegroundColor Red
  59. foreach ($line in ($output -split "`r?`n" | Where-Object { $_ })) { Write-Host " $line" }
  60. if ($output -match 'EBUSY|EPERM') {
  61. Write-Host " A running clawdcursor has its files open. Close the editor / Claude sessions using it" -ForegroundColor Yellow
  62. Write-Host " (or run 'clawdcursor stop', and 'clawdcursor resume' afterwards), then re-run this command." -ForegroundColor Yellow
  63. } else {
  64. Write-Host " Retry in an elevated terminal, or set a user-writable npm prefix." -ForegroundColor Yellow
  65. }
  66. exit 1
  67. }
  68. # ── 3. Verify ─────────────────────────────────────────────────────────────────
  69. # Refresh PATH so we can find the newly installed command this session.
  70. $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
  71. $npmPrefix = (npm prefix -g 2>$null)
  72. if ($npmPrefix) { $npmPrefix = $npmPrefix.Trim() }
  73. $exe = Get-Command clawdcursor -ErrorAction SilentlyContinue
  74. Write-Host ""
  75. if ($exe) {
  76. $ver = (& clawdcursor --version 2>$null | Select-Object -Last 1)
  77. if (-not $before) {
  78. Write-Host " [OK] Clawd Cursor $ver installed!" -ForegroundColor Green
  79. } elseif ($before -eq $ver) {
  80. Write-Host " [OK] Clawd Cursor $ver is already the latest (reinstalled)." -ForegroundColor Green
  81. } else {
  82. Write-Host " [OK] Clawd Cursor updated: $before -> $ver" -ForegroundColor Green
  83. Write-Host " Restart any editor or Claude session that uses clawdcursor so it picks up $ver." -ForegroundColor Gray
  84. }
  85. # The installer only updates this global copy. The Claude Desktop extension
  86. # and the Claude Code plugin carry their own: list them so old ones show.
  87. Write-Host ""
  88. Write-Host " Copies of clawdcursor on this machine:" -ForegroundColor Cyan
  89. & clawdcursor versions 2>$null
  90. } elseif ($npmPrefix -and (-not ($env:Path -split ';' | Where-Object { $_ -eq $npmPrefix }))) {
  91. Write-Host " [OK] Installed, but npm's bin folder is not in your PATH." -ForegroundColor Yellow
  92. Write-Host " Add this to your PATH, then reopen your terminal:" -ForegroundColor Yellow
  93. Write-Host " $npmPrefix" -ForegroundColor White
  94. } else {
  95. Write-Host " [OK] Installed! Close and reopen your terminal to use 'clawdcursor'." -ForegroundColor Green
  96. }
  97. # ── 4. Next steps ──────────────────────────────────────────────────────────────
  98. # Detect prior consent (known path) so repeat installs don't re-prompt for it.
  99. $consentGiven = Test-Path "$HOME\.clawdcursor\consent"
  100. Write-Host ""
  101. if (-not $consentGiven) {
  102. Write-Host " Start here:" -ForegroundColor Cyan
  103. Write-Host " clawdcursor consent " -NoNewline -ForegroundColor Yellow
  104. Write-Host "One-time desktop-control authorization" -ForegroundColor Gray
  105. } else {
  106. Write-Host " [OK] Consent already accepted from a previous install." -ForegroundColor Green
  107. }
  108. Write-Host ""
  109. Write-Host " Then connect your agent (it brings the AI; clawdcursor is its tools):" -ForegroundColor Cyan
  110. Write-Host " - Claude Code: install the plugin (bundles the MCP server + skill," -ForegroundColor Gray
  111. Write-Host " no hand-edited config) -- see the README's plugin section." -ForegroundColor Gray
  112. Write-Host " - Claude Desktop: install the .mcpb extension from the GitHub release." -ForegroundColor Gray
  113. Write-Host " - Codex / Cursor / Windsurf / Zed: register " -NoNewline -ForegroundColor Gray
  114. Write-Host "clawdcursor mcp --compact" -ForegroundColor Yellow
  115. Write-Host " - A client that speaks MCP over HTTP: " -NoNewline -ForegroundColor Gray
  116. Write-Host "clawdcursor agent" -NoNewline -ForegroundColor Yellow
  117. Write-Host " (MCP on :3847, token auth)" -ForegroundColor Gray
  118. Write-Host " No API key in clawdcursor: your agent's host handles the model." -ForegroundColor Gray
  119. Write-Host ""
docs/install.sh · Bundled script · 109 lines · 2 findings marked
  1. #!/bin/bash
  2. # Clawd Cursor Installer for macOS / Linux
  3. # Usage: curl -fsSL https://clawdcursor.com/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 3 on GitHub
  4. # Specify version: VERSION=v2.1.0 curl -fsSL https://clawdcursor.com/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  5. #
  6. # Installs the published npm package globally (npm i -g clawdcursor) — no git
  7. # clone, no local build toolchain. On macOS the package's postinstall builds
  8. # and ad-hoc-signs the native helper from source automatically (needs the Xcode
  9. # command-line tools; the install continues and tells you how to finish if not).
  10. set -e
  11. set -o pipefail
  12. # VERSION maps to an npm dist-tag/version. The old git-branch default ("main")
  13. # and a leading "v" both normalise to npm's "latest"/"x.y.z" form.
  14. VERSION="${VERSION:-latest}"
  15. case "$VERSION" in
  16. main|latest|"") PKG="clawdcursor@latest"; DISPLAY_VERSION="latest" ;;
  17. *) PKG="clawdcursor@${VERSION#v}"; DISPLAY_VERSION="${VERSION#v}" ;;
  18. esac
  19. echo ""
  20. echo " /\___/\\"
  21. echo " ( >^.^< ) Clawd Cursor Installer"
  22. echo " ) ("
  23. echo " (_)_(_)_)"
  24. echo ""
  25. # ── 1. Check Node.js ─────────────────────────────────────────────────────────
  26. if ! command -v node &>/dev/null; then
  27. echo " ❌ Node.js not found. Install v20+ from https://nodejs.org"
  28. exit 1
  29. fi
  30. NODE_MAJOR=$(node -e "console.log(process.versions.node.split('.')[0])")
  31. if [ "$NODE_MAJOR" -lt 20 ]; then
  32. echo " ❌ Node.js $(node --version) is too old. Update to v20+: https://nodejs.org"
  33. exit 1
  34. fi
  35. echo " ✅ Node.js $(node --version)"
  36. # ── 2. Install from npm (updates an existing global copy in place) ───────────
  37. # The version already installed, so we can say "updated X -> Y" afterwards.
  38. BEFORE="$(npm ls -g clawdcursor --depth=0 --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(JSON.parse(s).dependencies.clawdcursor.version||"")}catch{}})' 2>/dev/null || true)"
  39. echo " 📦 Installing $PKG (global)..."
  40. if ! npm install -g "$PKG" --loglevel error; then
  41. echo ""
  42. echo " ❌ npm install failed."
  43. echo " If it was a permissions (EACCES) error, either:"
  44. echo " • set a user-writable npm prefix: npm config set prefix ~/.npm-global"
  45. echo " then add ~/.npm-global/bin to your PATH and re-run, or"
  46. echo " • re-run with elevated privileges: sudo npm install -g $PKG"
  47. exit 1
  48. fi
  49. # ── 3. macOS native helper note ──────────────────────────────────────────────
  50. # The npm postinstall already built + ad-hoc-signed the helper. TCC permissions
  51. # still need a human click; `clawdcursor grant` walks you through them.
  52. if [ "$(uname)" = "Darwin" ]; then
  53. echo " 🍎 macOS: grant Accessibility + Screen Recording when prompted —"
  54. echo " run: clawdcursor grant"
  55. fi
  56. # ── 4. Verify ─────────────────────────────────────────────────────────────────
  57. echo ""
  58. if command -v clawdcursor &>/dev/null; then
  59. NOW="$(clawdcursor --version 2>/dev/null | tail -n 1)"
  60. NOW="${NOW:-$DISPLAY_VERSION}"
  61. if [ -z "$BEFORE" ]; then
  62. echo " ✅ Clawd Cursor $NOW installed!"
  63. elif [ "$BEFORE" = "$NOW" ]; then
  64. echo " ✅ Clawd Cursor $NOW is already the latest (reinstalled)."
  65. else
  66. echo " ✅ Clawd Cursor updated: $BEFORE → $NOW"
  67. echo " Restart any editor or Claude session that uses clawdcursor so it picks up $NOW."
  68. fi
  69. # The installer only updates this global copy. The Claude Desktop extension
  70. # and the Claude Code plugin carry their own: list them so old ones show.
  71. echo ""
  72. echo " Copies of clawdcursor on this machine:"
  73. clawdcursor versions 2>/dev/null || true
  74. else
  75. NPM_PREFIX="$(npm prefix -g 2>/dev/null)/bin"
  76. echo " ✅ Installed, but npm's global bin folder isn't on your PATH."
  77. echo " Add this to your shell profile (~/.bashrc or ~/.zshrc):"
  78. echo " export PATH=\"$NPM_PREFIX:\$PATH\""
  79. echo " then reopen your terminal."
  80. fi
  81. # ── 5. Next steps ──────────────────────────────────────────────────────────────
  82. # Detect prior consent (known path) so repeat installs don't re-prompt for it.
  83. CONSENT_FILE="$HOME/.clawdcursor/consent"
  84. echo ""
  85. if [ ! -f "$CONSENT_FILE" ]; then
  86. echo " Start here:"
  87. echo " clawdcursor consent One-time desktop-control authorization"
  88. else
  89. echo " [OK] Consent already accepted from a previous install."
  90. fi
  91. echo ""
  92. echo " Then connect your agent (it brings the AI; clawdcursor is its tools):"
  93. echo " • Claude Code: install the plugin (bundles the MCP server + skill,"
  94. echo " no hand-edited config) — see the README's plugin section."
  95. echo " • Claude Desktop: install the .mcpb extension from the GitHub release."
  96. echo " • Codex / Cursor / Windsurf / Zed: register \`clawdcursor mcp --compact\`."
  97. echo " • A client that speaks MCP over HTTP: \`clawdcursor agent\` (MCP on :3847, token auth)."
  98. echo " No API key in clawdcursor: your agent's host handles the model."
  99. echo ""
src/surface/uninstall.ts · Bundled script · 158 lines · 2 findings marked
  1. /**
  2. * `clawdcursor uninstall`: stop the daemon, then remove clawdcursor's config, data, skill registrations, MCP entries and
  3. * build output.
  4. */
  5. import * as fs from 'fs';
  6. import * as path from 'path';
  7. import * as os from 'os';
  8. import * as readline from 'readline';
  9. import { execSync } from 'child_process';
  10. import { e } from './format';
  11. import { getPackageRoot } from '../paths';
  12. import { privateRunDir } from '../platform/ps-spawn';
  13. import { authHeaders, readToken } from './auth';
  14. import { daemonPortForClient, sweepAllLocks } from './pidfile';
  15. import { ourSkillRegistrations } from './skill-register';
  16. /**
  17. * Stop the daemon on the port it recorded (before the data dir and its token go), then every clawdcursor a lock proves.
  18. */
  19. export async function stopRunningDaemon(): Promise<void> {
  20. try {
  21. if (readToken()) {
  22. const resp = await fetch(`http://127.0.0.1:${daemonPortForClient()}/stop`, { method: 'POST', headers: authHeaders() });
  23. if (resp.ok) {
  24. console.log(` ${e('🛑', '[STOP]')} Stopped running server`);
  25. await new Promise(r => setTimeout(r, 1000)); // give it a moment to shut down
  26. }
  27. }
  28. } catch { /* server not running — that's fine */ }
  29. // Only a holder its lock proves is clawdcursor is signalled; a stale lock is just deleted (sweepAllLocks).
  30. for (const r of await sweepAllLocks()) {
  31. if (r.outcome === 'stopped') console.log(` ${e('🛑', '[STOP]')} Killed running ${r.mode} process (pid ${r.pid})`);
  32. }
  33. }
  34. export async function runUninstall(): Promise<void> {
  35. if (!process.stdin.isTTY || !process.stdout.isTTY) {
  36. console.error(`\n${e('❌', '[ERR]')} clawdcursor uninstall requires an interactive terminal.\n`);
  37. process.exit(1);
  38. }
  39. const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  40. const answer = await new Promise<string>((resolve) => {
  41. rl.question(`\n${e('⚠️', '[WARN]')} This will remove all Clawd Cursor config and data. Continue? (y/N) `, resolve);
  42. });
  43. rl.close();
  44. if (answer.toLowerCase() !== 'y') {
  45. console.log('Cancelled.');
  46. return;
  47. }
  48. console.log(`\n${e('🗑️', '[DEL]')} Uninstalling Clawd Cursor...\n`);
  49. const clawdRoot = getPackageRoot();
  50. const homeDir = os.homedir();
  51. let removed = 0;
  52. const failed: string[] = [];
  53. // Resilient remove: never let one locked / permission-denied path abort the
  54. // whole uninstall. On Windows a file handle (a running daemon, the logger's
  55. // current log file, AV/indexer) can briefly hold a path open → EPERM/EBUSY.
  56. // rmSync's maxRetries rides out the transient lock; the try/catch downgrades
  57. // a hard failure to a warning + manual-cleanup hint and CONTINUES to the next
  58. // step.
  59. const safeRemove = (target: string, label: string): void => {
  60. try {
  61. if (!fs.existsSync(target)) return;
  62. const stat = fs.lstatSync(target);
  63. if (stat.isSymbolicLink() || stat.isFile()) fs.unlinkSync(target);
  64. else fs.rmSync(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
  65. console.log(` ${e('🗑️', '[DEL]')} Removed ${label}`);
  66. removed++;
  67. } catch (err) {
  68. const code = (err as NodeJS.ErrnoException).code || (err as Error).message;
  69. failed.push(`${target} (${code})`);
  70. console.log(` ${e('⚠️', '[WARN]')} Could not remove ${label} (${code}) — close any running clawdcursor, then delete manually: ${target}`);
  71. }
  72. };
  73. await stopRunningDaemon();
  74. const configFiles = [
  75. path.join(clawdRoot, '.clawdcursor-config.json'),
  76. path.join(clawdRoot, '.clawdcursor-favorites.json'), // written by installs before 1.6
  77. path.join(clawdRoot, '.env'),
  78. ];
  79. for (const f of configFiles) safeRemove(f, path.basename(f));
  80. safeRemove(path.join(homeDir, '.clawdcursor'), path.join(homeDir, '.clawdcursor'));
  81. safeRemove(path.join(homeDir, '.clawd-cursor'), `legacy ${path.join(homeDir, '.clawd-cursor')}`);
  82. safeRemove(path.join(clawdRoot, 'debug'), 'debug/');
  83. for (const sp of ourSkillRegistrations(homeDir)) safeRemove(sp, `skill registration: ${sp}`);
  84. const mcpConfigs = [
  85. path.join(homeDir, '.claude', 'settings.json'),
  86. path.join(homeDir, '.claude', 'settings.local.json'),
  87. path.join(homeDir, '.cursor', 'mcp.json'),
  88. path.join(homeDir, '.windsurf', 'mcp.json'),
  89. path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json'),
  90. path.join(homeDir, '.vscode', 'mcp.json'),
  91. ];
  92. for (const configPath of mcpConfigs) {
  93. try {
  94. if (!fs.existsSync(configPath)) continue;
  95. const raw = fs.readFileSync(configPath, 'utf-8');
  96. const json = JSON.parse(raw);
  97. const servers = json.mcpServers || json.servers || {};
  98. let found = false;
  99. for (const key of Object.keys(servers)) {
  100. if (key.toLowerCase().includes('clawdcursor') || key.toLowerCase().includes('clawd-cursor')) {
  101. delete servers[key];
  102. found = true;
  103. }
  104. }
  105. if (found) {
  106. fs.writeFileSync(configPath, JSON.stringify(json, null, 2) + '\n');
  107. console.log(` ${e('🗑️', '[DEL]')} Removed MCP entry from ${configPath}`);
  108. removed++;
  109. }
  110. } catch { /* skip unreadable configs */ }
  111. }
  112. safeRemove(path.join(clawdRoot, 'dist'), 'dist/');
  113. // macOS native helper build output — regenerable, not tracked (#155).
  114. safeRemove(path.join(clawdRoot, 'native', '.build'), 'native/.build/');
  115. safeRemove(path.join(clawdRoot, 'native', 'ClawdCursor.app'), 'native/ClawdCursor.app/');
  116. try {
  117. // Left on PATH on purpose: the user runs this uninstall themselves, and npm is theirs to resolve (not a system program).
  118. execSync('npm unlink -g clawdcursor', { stdio: 'pipe', timeout: 15000, cwd: privateRunDir() });
  119. console.log(` ${e('🗑️', '[DEL]')} Removed global clawdcursor command`);
  120. removed++;
  121. } catch { /* may not be linked globally */ }
  122. if (removed === 0 && failed.length === 0) {
  123. console.log(' Nothing to clean up.');
  124. }
  125. if (failed.length > 0) {
  126. console.log(`\n${e('⚠️', '[WARN]')} ${failed.length} item(s) could not be removed (a running process likely held a file open). Close any clawdcursor process, then delete these manually:`);
  127. for (const f of failed) console.log(` ${f}`);
  128. }
  129. console.log(`\n${e('🐾', '>')} ${failed.length > 0 ? 'Uninstall finished with warnings' : 'Fully uninstalled'}. To remove the source code, delete:`);
  130. console.log(` ${clawdRoot}`);
  131. // Closing the reinstall dead-end: this command just removed the global
  132. // `clawdcursor` shim, so no `clawdcursor` command works afterwards — and
  133. // the natural next step shouldn't be a guess. Point the user at the package
  134. // manager (works everywhere) plus the turnkey one-liner for their OS.
  135. const reinstallOneLiner = process.platform === 'win32'
  136. ? 'irm https://clawdcursor.com/install.ps1 | iex'
  137. : 'curl -fsSL https://clawdcursor.com/install.sh | bash';
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 155 on GitHub
  138. console.log(`\n${e('📦', '>')} To reinstall: npm i -g clawdcursor`);
  139. console.log(` or: ${reinstallOneLiner}\n`);
  140. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.