amrdab/clawd-cursor/clawd-cursor-2

If you are a human: see `README.md`. This file is the AI-facing manual — dense on purpose.

If you are an LLM: keep going.

FALLBACK ONLY. Check these first — they're cheaper, faster, more reliable:

1. Native API (Gmail, GitHub, Slack, Stripe …) → use the API.

2. CLI (git, gh, aws, npm, curl) → use the CLI.

3. Direct file edit → do that.

4. Existing browser automation (Playwright, Puppeteer) → use that.

None apply? Now use clawdcursor. It's the last mile — when the only remaining surface is a GUI. If a human can do it on a screen, you can too.

Capabilities & rules:

- CAN: open apps, click, type, fill forms, read the screen (a11y tree / OCR / screenshot), drive browsers and native apps.

- MUST: respect safety tiers (Auto = free, Confirm = ask user). Ask before touching email, banking, messaging, or password managers.

- clawdcursor is your hands and eyes on the user's machine — used with their permission.

The easiest path - one tool, natural-language task (START HERE)

If you are an LLM reading this: YOU SHOULD BE USING COMPACT MODE.

- MCP stdio (editor host): add "args": ["mcp", "--compact"] to your config.

- MCP over HTTP (daemon mode): start the daemon with --compact (or set

CLAWD_MCP_COMPACT=1) so /mcp serves the 7 compound tools (incl. batch). The surface is

fixed at startup — a daemon serves EITHER the compact tools OR the 98

granular ones, not both. Default (no flag) is granular.

Granular mode's 98 tools are kept for back-compat. Compact's tools are much smaller and reduce mis-tool-selection. Use granular only if your runtime MUST have every primitive as its own top-level schema.

If you connect via MCP with --compact, you get a single tool that takes the whole task:

task({"instruction": "open Notepad and type hello"})
task({"instruction": "send an email in Outlook to amy@x.com saying I'll be late"})
task({"instruction": "find the file README.md in Downloads and open it"})

clawdcursor's built-in agent loop takes the wheel: it perceives the desktop, acts with the toolbox, and iterates until done, then returns a trace.

`task` vs. compound tools — pick one, never both:

• Editor-host LLM (Claude Code, Cursor, Windsurf, Zed, OpenClaw, Claude Agent SDK — anything with its own agent loop): use compound tools directly. Calling task creates a loop-inside-a-loop; the inner loop can't see your higher-level goal and you pay for two models to plan the same work.
• External script / one-shot client with no agent loop — or a frontier model delegating grunt work: task({"instruction": "..."}) is what you want. clawdcursor reasons AND acts using the model configured via clawdcursor doctor.

If unsure: you are almost certainly the first case. Use the compound tools.

When you need step-level control - 7 compound tools

The compact surface collapses every primitive into six action-discriminated compound tools, mirroring Anthropic's computer_20250124 pattern:

computer(action, ...)       Direct mouse / keyboard / screenshot / wait
accessibility(action, ...)  Read the a11y tree, click by name, set values, toggle
window(action, ...)         Open apps / focus / maximize / minimize / close / resize
system(action, ...)         Clipboard / time / OCR / undo / shortcuts / delegate
browser(action, ...)        DevTools Protocol - DOM-level control of any CDP-capable browser (Chrome, Edge, Chromium, Brave)
task({instruction})         See above - delegate a whole task to the built-in thin agent loop
batch({steps})              Collapse N tool calls into one round-trip (see "Execution playbook" below)

Pick a compound FIRST based on what kind of operation it is, then set the action enum, then supply the args. The catalog is ~7,000 tokens - about a third of the granular surface's ~20,000 - so small models (Haiku, Kimi, Ollama) stay focused.

Cost tier - always use the cheapest tier that works

Rule: start at T1. Escalate to the next tier only when the current one fails. Apply this logic when calling compound tools directly; the built-in agent loop (via task({...})) follows the same discipline.

Quick reference - what action to pick

I want to click something:

• By name? → accessibility({"action":"invoke","name":"Send"}). Most reliable.
• By text via CDP on a web page? → browser({"action":"click","text":"Submit"}).
• By screen coordinates? → computer({"action":"click","x":500,"y":300}). Last resort.

I want to type:

• Into a named field? → accessibility({"action":"set_value","name":"Email","value":"x@y.com"}).
• Into the focused element? → computer({"action":"type","text":"hello"}).
• In a browser? → browser({"action":"type","label":"Email","text":"x@y.com"}).

I want to read the screen:

• Structured (buttons, fields, text with coords)? → accessibility({"action":"read_tree"}). First choice.
• Raw OCR fallback? → system({"action":"ocr"}).
• Pixel image? → computer({"action":"screenshot"}). Last resort - expensive.

I want to open / focus something:

• An app? → window({"action":"open_app","name":"Notepad"}).
• A URL? → window({"action":"open_url","url":"https://..."}).
• A file? → window({"action":"open_file","path":"/home/..."}).
• Focus an existing window? → window({"action":"focus","processName":"chrome"}).

I want to press a keyboard shortcut:

• computer({"action":"key","combo":"mod+s"}) - mod auto-resolves to Cmd on macOS, Ctrl elsewhere.

I want to draw a curve / freehand path (one continuous stroke):

• computer({"action":"drag_path","path":"[{\"x\":100,\"y\":100},{\"x\":120,\"y\":110},...]"})

The path is a JSON array of {x, y} points. The mouse button stays held for the entire path - one continuous stroke, not a series of disconnected drags. Use this for drawing in Paint / Figma / any canvas app. mouse_drag alone (start → end) gives you a straight line; drag_path gives you curves.

The web app is eating my Escape / keyboard events:

• Web-wrapped apps (New Outlook, Teams, Gmail, Notion) treat Escape as "close this dialog/modal" - often closing the entire compose window. Do NOT send Escape to dismiss autocomplete suggestions in web apps. Use arrow keys (Up/Down to navigate the dropdown, Enter to pick), or click somewhere neutral with computer({"action":"click","x":..,"y":..}) to blur the field.

When to reach for this skill

Use clawdcursor when:

• The user names an app, window, or "my screen" (Outlook, Figma, Zoom, a legacy tool with no REST endpoint).
• The task is "click / type / read / open / focus / drag" on something visible.
• A web task must work without a Playwright script — drive the live browser via the browser (CDP) compound.
• A previous approach (API, CLI, file edit) already failed and the only remaining surface is a GUI.
• The user describes a workflow done by hand: "export from Excel", "send via GUI", "copy text from Notes to Slack".

In OpenClaw terminology: clawdcursor is a skill that dispatches to tools (API / CLI / GUI primitives). Route API / CLI / file-edit first; reach for clawdcursor only when the GUI surface is all that remains.

⚠️ Sensitive App Policy

You MUST ask the user before accessing:

• Email clients (Gmail, Outlook, Apple Mail, Thunderbird)
• Banking or financial apps
• Private messaging (WhatsApp, Signal, Telegram, iMessage, Messages)
• Password managers (1Password, Bitwarden, LastPass, Keychain)
• Admin panels, cloud consoles, production dashboards

Never self-approve actions on these surfaces. The safety layer elevates them to Confirm automatically - do not bypass. If you see a Confirm dialog, show it to the user and wait for their answer.

Modes at a glance

clawdcursor exposes one protocol (MCP) over two transports. The daemon's behavior depends on whether an LLM is configured via clawdcursor doctor, not on a flag.

In mcp (stdio) and tools-only agent (HTTP): you reason, clawdcursor acts. There is no built-in LLM in the loop. You call tools, interpret results, decide next steps. In autonomous agent mode (LLM configured): clawdcursor's thin loop reasons AND acts — it perceives the desktop, selects tools, and iterates until done. Call task (compact) or submit_task (granular) with a natural-language instruction, then poll agent_status.

Connecting

MCP (recommended for Claude Code / Cursor / Windsurf / Zed)

Compact - recommended for every LLM agent:

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

Granular - 98 individual tools (power-user, back-compat, larger prompt budget):

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

HTTP MCP (for any HTTP-capable agent)

clawdcursor agent            # starts on http://127.0.0.1:3847; built-in agent lights up if an LLM is configured

The HTTP transport uses MCP's streamable-HTTP envelope (JSON-RPC over POST), not REST. All requests go to a single endpoint, POST /mcp, with Authorization: Bearer <token> from ~/.clawdcursor/token. Stateless mode - no session-init handshake required for one-shot calls.

POST /mcp        → JSON-RPC: tools/list, tools/call (the catalog + every tool)
GET  /mcp        → SSE channel for server-initiated notifications (auth)
GET  /health     → {"status":"ok","version":"<x.y.z>"}  (no auth, readiness probe)
POST /resume     → answer a pause for the user: {"answer":"resume"|"end"} (auth, localhost-only; same as `clawdcursor resume`)
POST /stop       → graceful shutdown (auth, localhost-only)
GET  /           → minimal dashboard, calls /mcp via JSON-RPC under the hood

That's the entire HTTP surface. Calling a tool looks like:

POST /mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "open_app",
    "arguments": {"name": "Notepad"}
  }
}