1.5.24 — The AI never touches your pill, and failures stop looking like results.
While a pause waits for you, nothing reads, clicks or types. The pill and pause prompt are never a target, even from another clawdcursor process.
Local MCP server that gives any AI agent safe cross-OS desktop control — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available. Works with any tool-calling model (Claude, GPT, Gemini, Llama) on Windows, macOS, and Linu
2026-11-14
ดาว
—
เครื่องมือ
—
อัปไทม์
—
On macOS, a screenshot without Screen Recording permission is an error, not a wallpaper image, and open popovers are readable.
The browser clawdcursor drives comes to the front when it navigates.
A failed OCR read reports its error instead of "No text detected", and OCR confidence is only shown when the engine really has one.
1.5.23 — Windows: finding an element by name no longer matches stray letters. A lone "C" on another page could match "User code 0", and "Don't Save" could match Save. A partial match now has to be a real part of the name you asked for.
1.5.22 — Your turn is as short as possible. When an agent needs you (a sign-in, a 2FA code), it asks for that one step and does the rest itself. With done_when (what shows on screen once you're done), the prompt turns from blue back to amber the moment you finish, with no Resume click.
1.5.21
set_value never guesses a field. With no field name or role it used to type into the window's largest text box; it now asks you to name the field.
macOS: no screen-recording permission no longer breaks everything. Only screenshots and OCR fail, and they say how to fix it; windows, keys and accessibility keep working.
Cleaner page text on Windows (no placeholder characters), and a security update to a dependency.
1.5.20
The on-screen pill no longer blocks the agent's own clicks. It sits where browsers keep their tabs and address bar; it now steps aside for a moment before every click, drag or scroll, then comes back. Windows, macOS and Linux.
Reading a page no longer highlights it on Linux and macOS either.copy_all_text reads the document through accessibility, as on Windows: exact text, nothing selected, your clipboard untouched.
Your clipboard is put back after typing (smart_type too), and only once the paste has landed, so a slow app can't paste what you had copied.
macOS:window focus focuses the process you asked for, a locked screen says so, sidebar clicks are verified, and a bare modifier key (shift) works.
1.5.19 — Typing never pastes your own clipboard. clawdcursor types by pasting; on Windows a clipboard write could fail silently and the paste then sent whatever you had copied. Every paste now checks the clipboard first and types key by key when it doesn't hold the text.
1.5.18
"Something else" on the pause prompt. When the agent pauses for you, the prompt has a third button between Resume and End task: type an answer instead of doing the step — "use the test account instead", a code, a change of plan — and press Enter. The agent continues from what you wrote. Windows, macOS and Linux; over MCP pause_for_user returns {status:"replied", reply}.
Reading a page no longer highlights it (Windows).copy_all_text reads the document the way a screen reader does: exact text, no Ctrl+A, nothing selected, your clipboard untouched.
MCP tool annotations on every tool, and window / system now describe every action, its side effects and what it returns.
copy_all_text never selects an editor or a list (Ctrl+A there selected a whole document or every email).
1.5.16
It pauses for you at a roadblock, then carries on. A sign-in, a 2FA code, a CAPTCHA, an upgrade page: instead of giving up, the agent pauses. The glow around the screen turns blue and an on-screen prompt says what it needs ("Sign in to Outlook, then click Resume"). Click Resume and it continues where it left off, or End task to stop. Your own agent can do the same over MCP with system({ action: "pause_for_user", message }); from a terminal, clawdcursor resume (or --end).
The glow and banner on every OS. macOS and Linux now get the same screen-edge glow and banner as Windows: amber while the agent works, blue while it waits for you. Double-click the banner to stop everything.
Blind mode on macOS caught up with Windows. A native accessibility helper lists windows in 0.3 s (was 11 s) and reads a window's tree in 0.06–0.2 s. Typing is refused while a system dialog owns the keyboard, and the agent is told when another app's dialog took its keys.
Sharper blind mode on Windows and Linux. Classic controls no longer read as blank panes, the open dialog is what gets read, no 10 s stall on buttons that open a modal, the right field is found by name, and focusing a window no longer un-maximizes it.
Upgrade walls are a roadblock. Clicks on Upgrade, Subscribe or Start trial need confirmation.
Know what you're running.clawdcursor versions lists every installed copy (global npm, Claude Desktop extension, Claude Code plugin), and the installers say what they updated.
Clawd Cursor is a local MCP server that gives any tool-calling agent — Claude Code, Cursor, Windsurf, OpenClaw, the Claude Agent SDK, or your own loop — safe control of the real desktop. It clicks, types, reads the screen, opens apps, and drives any GUI the way a human would: native apps, the browser, even a canvas.
Most "let an agent use the computer" tools take a screenshot and feed it to a vision model — slow, expensive, and brittle. Clawd Cursor compiles the screen into one UI map: it fuses the accessibility tree and OCR into a confidence-scored set of elements, each tagged with a stable el_NN id, and acts on elements by id — not pixel coordinates. Coordinates appear only in the last-resort screenshot/vision tier (live pixels off the current frame), for canvas-only apps or tasks that genuinely need spatial reasoning. The result is cheaper, faster, private, and — uniquely — it checks that each action actually did what it claimed.
If a human can do it on a screen, your agent can too. No API, no integration, no problem — only the right sequence of reads, clicks, keys, and waits. Use it as the last-mile fallback: native API exists? Use it. CLI? Use it. Clawd Cursor is for the click, the legacy app, the GUI with no public surface.
Why it's different
The desktop-agent space is crowded. The closest install-and-go peers are Windows-MCP and Terminator (desktop MCP servers); browser-only tools (browser-use, Playwright MCP) are adjacent; and OmniParser / UI-TARS are vision-centric parsing approaches you'd build an agent around, not products you install. Here's the honest comparison across those approaches — what Clawd Cursor does that the popular options don't:
Clawd Cursor
browser-use
Playwright MCP
OmniParser / UI-TARS
computer-use
Any desktop app, not just the web
✅
web only
web only
✅
✅
Cross-OS (Windows + macOS + Linux)
✅
—
—
varies
sandbox
Perception without a vision model
✅ compiled a11y + OCR map
DOM
a11y tree
❌ vision-centric
❌ vision
Verifies its own actions (deviation)
✅
—
—
—
—
Single safety chokepoint (allow/confirm/block)
✅
—
—
—
—
Any model / vendor
✅
✅
not an agent
model-specific
Claude only
MCP-native (one config, any host)
✅
library
test framework
—
tool-use API
Local-only, no cloud required
✅
✅
✅
needs a model
screens → cloud
Three things here are genuinely rare:
Cheapest-tier-first perception, fully local. Accessibility tree (free) → OCR (cheap) → screenshot (expensive — the only tier that puts pixels in the model's context; "screenshot" and "vision" are the same step). The agent climbs only when it must, so token cost tracks task difficulty — and with a local model, nothing leaves the machine. Vision-centric agents (OmniParser, UI-TARS) need a screenshot in the model for every observation.
It verifies. Pass expect on a consequential action and Clawd Cursor re-checks the live screen (with a short settle window for async UIs) and reports a DEVIATION instead of a hollow "success." A completed task can't be marked done on evidence that was already true before it acted.
One safety gate. Every call — from an editor over stdio, an external agent over HTTP, or the built-in loop — routes through a single safety.evaluate() chokepoint (allow / confirm / block) before it touches the desktop. The agent cannot bypass it.
Plus: whenever an agent is driving, an on-screen "desktop control in progress" banner and an amber glow around the screen edges, on Windows, macOS and Linux — double-click the banner to stop. When the agent needs you (a sign-in, a 2FA code), the glow turns blue and the banner says what to do, with Resume and End task. A human at the machine always knows, and always has a kill switch.
Install
clawdcursor is an MCP server published to npm — install it into any MCP-capable
agent (Claude Code, Claude Desktop, Cursor, Windsurf, Zed, OpenAI Codex, or your own
loop) the same way you install any other MCP server.
Claude Desktop — one-click extension (no terminal)
Download the extension for your OS and open it — Claude Desktop installs it:
Double-click the file (or Settings → Extensions → Advanced settings → Install
Extension… and pick it).
Turn on Allow clawdcursor to control this computer — that is the one-time
desktop-control consent; until it is on, every tool returns a consent prompt.
macOS: the first time macOS asks, allow Claude under Privacy & Security →
Accessibility and Screen Recording.
No Node.js, npm or JSON editing needed — Claude Desktop runs the bundled server
itself. Everything below is for other agents, or for Claude Desktop without the
extension.
1 — Install the engine + grant consent (once)
npm i -g clawdcursor
clawdcursor consent --accept # one-time desktop-control consent (required)
clawdcursor grant # macOS only — approve Accessibility + Screen Recording
Hosts that support MCP elicitation (e.g. Claude Code, VS Code) also let you skip
consent --accept: the first tool call asks "Allow clawdcursor to control this
computer" right in the app.
Zero-install also works — swap clawdcursor for npx -y clawdcursor in any
snippet below and npx fetches it on demand. A global install is recommended
anyway: it's pinnable and inspectable on disk (safer for a tool with full desktop
control than auto-fetching latest every run), and it's the path on which the macOS
native helper builds at install time. Requires Node.js 20+.
Per-OS prerequisites.Windows installs clean — sharp and @nut-tree-fork/nut-js
ship prebuilt binaries, so no C++/Python build tools are needed. macOS needs Xcode
Command Line Tools (xcode-select --install) for screenshots / vision; core
accessibility-driven control still works without them. Linux needs a few system
packages npm can't install: tesseract-ocr (OCR), python3-gi + gir1.2-atspi-2.0
(accessibility tree), and — on Wayland — ydotool (synthetic input).
2 — Add it to your agent (pick your host)
One click (Cursor, VS Code):
Every host runs the same command — clawdcursor mcp --compact, or
npx -y clawdcursor mcp --compact with no global install. Only the config shape
differs between hosts:
Claude Code
claude mcp add clawdcursor -s user -- clawdcursor mcp --compact
Cursor · Windsurf · Claude Desktop · Cline · Gemini CLI — the common mcpServers shape:
Any other MCP host (Goose, Continue, …) — register a stdio server with command
clawdcursor and args mcp --compact.
Windows: some hosts start the server without a shell, and then can't find
clawdcursor or npx (both are .cmd shims). If the server won't start, wrap it in
cmd /c — e.g. "command": "cmd", "args": ["/c", "clawdcursor", "mcp", "--compact"],
or claude mcp add clawdcursor -s user -- cmd /c clawdcursor mcp --compact.
That's the whole setup. Ask your agent: "open Outlook and reply to the latest email
from Sarah."
Or: one-command plugin (Claude Code)
Skip the manual config — this repo ships a plugin that registers the tools and
bundles the usage skill in one step. It resolves the package's bin (never a
hard-coded dist/ path), so an upgrade can't break it:
claude plugin marketplace add AmrDab/clawdcursor
claude plugin install clawdcursor@clawdcursor
# Windows (PowerShell)
powershell -c "irm https://clawdcursor.com/install.ps1 | iex"
# macOS / Linux
curl -fsSL https://clawdcursor.com/install.sh | bash
Notes. You never run clawdcursor mcp yourself — the host spawns it over stdio
on demand. clawdcursor doctor is not part of MCP setup; it only configures the
built-in LLM for the autonomous agent daemon. On macOS, Accessibility is
required (primary control path); Screen Recording is optional (vision fallback
only). For editor permission allowlists, use the server-level wildcard
mcp__clawdcursor rather than per-tool entries — it survives tool renames.
The engine
The perception + verification core (the UI State Compiler, since v1.5.0):
compile_ui fuses the accessibility tree and OCR into one confidence-scored map of the screen, every element tagged with a stable el_NN id. Act on an element by {element_id, snapshot_id} instead of pixels — near-free in tokens, and it survives DPI, resize, and layout shifts. find_button / find_field locate a target by meaning and hand you the id.
Reactive verification.expect on an action → Clawd Cursor confirms the outcome on the live screen and returns a DEVIATION when the UI didn't obey.
Cross-platform parity. The compiler, secure-field redaction, and coordinate handling run on Windows, macOS, and Linux; the external-agent (MCP) surface resolves el_NN refs through the safety gate and discloses when it attached to your existing browser.
Set-of-Mark-style element IDs and a11y/OCR fusion aren't new ideas on their own — what's rare is doing them locally, a11y-first (no vision model required), with a built-in verification gate and one safety chokepoint, across three operating systems, behind a single MCP config.
Where the brain lives decides how you run it. Both modes can run side-by-side.
Brain lives…
Mode
Command
What you call
In your editor (Claude Code, Cursor, Windsurf, Zed)
Direct tools
clawdcursor mcp
Each tool, via stdio MCP
In a headless agent with its own LLM (OpenClaw, Agent SDK, your loop)
Direct tools
clawdcursor agent --no-llm
Same, over HTTP MCP
Inside Clawd Cursor itself (scheduled / "submit and walk away")
Thin agent loop
clawdcursor agent + doctor-configured LLM
task / submit_task
External brain that delegates sub-tasks to the built-in loop
Direct + delegation
clawdcursor agent + your client
task({instruction:…}) to hand off
The loop
Read the a11y tree (cheap) → act on named targets → verify from fresh observations → escalate perception only when needed (OCR → screenshot, the one tier that sends pixels to the model). Sparse a11y tree? system.detect_webview switches Electron/WebView2 apps to browser.* over CDP. Canvas-only (Paint, Figma, games)? Screenshot + coordinate click.
batch for deterministic stretches. When the next N steps are known, collapse them into one call — each step still routes through the safety gate; on any guard miss or error the batch halts with a per-step trace.
Task delegation. With an LLM configured on the daemon, an external agent can hand off at any point: task({"instruction":"…"}). The built-in loop takes the wheel and reports back — offload grunt work to a cheaper model without burning your own context.
The toolbox
Two catalogs ship side-by-side. The toolbox is 7 compound tools, each with an action enum covering ~10–20 verbs (about 7,000 tokens for the whole catalog, schemas included — about a third of the granular surface's ~20,000; the computer_20250124 shape editor hosts already know). The granular surface is the 98 underlying primitives, one schema per verb (for runtimes that need top-level tools, or for debugging). Both run through the same safety.evaluate() chokepoint; the full catalog is always visible via MCP tools/list.
run (default; bounded-sync — waits up to timeouts, returns {status:"running"} + progress if longer, re-call to keep waiting), status, abort, resume (continue a task paused for the user). Delegates to the built-in loop. Requires clawdcursor agent with an LLM.
batch
{steps:[…]} — collapse N calls into one round-trip; each step {name, arguments, expect?}, re-perceived and safety-gated, halts with a trace on any miss.
computer({ action: "key", combo: "mod+s" }) // Cmd+S / Ctrl+S, resolved per-OS
accessibility({ action: "invoke", name: "Send" }) // click by name, not pixels
window({ action: "open_app", name: "Outlook" })
task({ instruction: "open Notepad and type hello" }) // hand off to the thin loop
Cheapest-tier-first perception
Every observation has a cost. Start at the cheapest rung that works; climb only when it fails. The live log (CLAWD_LOG=pretty, default on a TTY) shows the ladder in real time via per-call badges.
Headless agents, daemons, orchestration, Agent SDK. POST JSON-RPC to http://127.0.0.1:3847/mcp.
Run clawdcursor agent. Bearer token at ~/.clawdcursor/token.
# HTTP MCP — list tools
# (the Accept header is required — the MCP spec's Streamable HTTP transport
# rejects requests that don't accept both JSON and SSE with a 406)
curl -s -X POST http://127.0.0.1:3847/mcp \
-H "Authorization: Bearer $(cat ~/.clawdcursor/token)" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Platform support
Platform code lives behind a single PlatformAdapter interface (src/platform/{windows,macos,linux}.ts + wayland-backend.ts). Business logic never reads process.platform.
Platform
UI Automation
OCR
Browser (CDP)
Input
Windows 10/11 (x64 / ARM64)
UIA via PowerShell bridge
Windows.Media.Ocr
Chrome / Edge
nut-js
macOS 12+ (Intel / Apple Silicon)
Native AX helper (Swift), JXA fallback
Apple Vision
Chrome / Edge
nut-js + System Events
Linux X11
AT-SPI via python3-gi
Tesseract
Chrome / Edge
nut-js
Linux Wayland
AT-SPI via python3-gi
Tesseract
Chrome / Edge
ydotool / wtype
Windows — no setup; the PowerShell bridge spawns on demand.
macOS — first run needs Accessibility (required) + Screen Recording (optional); clawdcursor grant walks the dialogs. Retina/HiDPI handled in-adapter — don't pre-scale coordinates.
Linux X11 — apt install tesseract-ocr python3-gi gir1.2-atspi-2.0.
Linux Wayland — same, plus ydotool + ydotoold (preferred) or wtype (keyboard only).
Safety & privacy
Tier
Actions
Behavior
Allow
Reading, opening apps, navigation, typing into non-sensitive fields, minimize
Pauses instead of pushing through. At a sign-in, 2FA, CAPTCHA or plan-limit page the agent hands the desktop to you (blue glow, Resume / End task) instead of guessing. A pause times out after 15 minutes (CLAWD_PAUSE_TIMEOUT_MIN); CLAWD_NO_PAUSE=1 turns pausing off.
No telemetry by default. Nothing phones home. Screenshots stay in RAM; with a local model nothing leaves the machine; with a cloud provider, screenshots go only to the endpoint you configured. clawdcursor report is opt-in and previews exactly what it sends.
Prompt-injection defense. Screen text is returned inside <untrusted-screen-content> tags — data, never instructions.
PlatformAdapter + Windows / macOS / Linux / Wayland, OCR engine, CDP driver, URI handler.
src/llm/
Provider clients (Claude, GPT, Gemini, Llama, Kimi, Ollama, …), credentials, model config.
src/surface/
CLI, MCP server (stdio + HTTP), dashboard, doctor, onboarding, control banner.
The PlatformAdapter is the only thing platform code talks to; safety.evaluate() is the only way tools execute. Those two seams are the whole point.
CLI
For humans diagnosing an install. Agents connect via MCP.
clawdcursor consent Manage desktop-control consent (--accept / --revoke / --status)
clawdcursor grant Grant macOS permissions (interactive, macOS only)
clawdcursor doctor Configure the AI provider for `agent` mode (+ diagnostics)
clawdcursor status Readiness check (consent, permissions, AI config)
clawdcursor versions Every installed copy and its version (global, Claude Desktop extension, Claude Code plugin)
clawdcursor resume Continue a task paused for you (same as the on-screen Resume); --end to stop it
clawdcursor mcp stdio MCP server — editor hosts spawn this; you don't
clawdcursor agent Daemon: HTTP MCP on :3847, optional built-in thin loop
clawdcursor agent --no-llm Daemon, tool surface only (no built-in brain)
clawdcursor stop Stop every running mode
clawdcursor uninstall Remove all config and data
Options: --port <n> (default 3847) · --compact · --no-banner · --provider <name> · --accept
Development
git clone https://github.com/AmrDab/clawdcursor.git && cd clawdcursor
npm install
npm run build # tsc + postbuild → dist/surface/cli.js
npm test # vitest (1,000+ tests)
npm run lint # eslint
npm link # global `clawdcursor` shim (Admin shell on Windows)
Tests run on Node 20 & 22 against Ubuntu, macOS, and Windows in CI, plus a coverage ratchet, a perf tripwire, and an npm audit gate.
PRs welcome — see CONTRIBUTING.md for the dev loop, branch conventions, and the test matrix every change clears. Bugs and features in issues; private security reports via SECURITY.md.
Built on the Model Context Protocol SDK, nut-js, Playwright, the Anthropic computer_20250124 tool shape, and the AT-SPI / UIA / AX trees that make app-agnostic GUI automation possible at all.
Local MCP server that gives any AI agent safe cross-OS desktop control — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available. Works with any tool-calling model (
Local MCP server that gives any AI agent safe cross-OS desktop control — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available. Works with any tool-calling model (Claude, GPT, Gemini, Llama) on Windows, macOS, and Linu
ตรวจสอบล่าสุดเมื่อ 2026-11-14 Local MCP server that gives any AI agent safe cross-OS desktop control — the fallback execution layer for when APIs, CLIs, and direct integrations aren't available. Works with any tool-calling model (Claude, GPT, Gemini, Llama) on Windows, macOS, and Linu