agentcursor: Instructions file for Codex

AgentCursor: guide for coding agents

AgentCursor gives an AI agent a visible, human-paced cursor. It has two surfaces, and they are separate code paths.

Surface	What it drives	Code	Needs
Browser extension	Chrome tabs (real profile, logged in)	src/ (Node MCP server) + extension/ (MV3)	Node, pnpm, Chrome, the extension loaded
Computer use (Rust core)	Any macOS app window	rust/ (one binary, agentcursor)	Rust toolchain, macOS arm64, Accessibility permission

Details: docs/extension.md and docs/computer-use.md.

Which one to pick

• Task is inside a web page (read DOM, click, type, tabs, JS evaluate): browser extension. Tools: read_page, click, type, tabs, evaluate.
• Task is a native app (Notes, Finder, Safari chrome, TextEdit, System Settings): computer use.
• Computer use must not disturb the user (front app and pointer stay put): the Rust core. It clicks and types through accessibility actions.
• Rust core is not wired under the Node desktop_* tools. The Node server has its own desktop_* implementation (Swift helper) that moves the real cursor.
• The Claude Code plugin (.mcp.json) still launches the Node server, not the Rust binary.

Install and connect

Browser extension and Node server:

pnpm install && pnpm build
node dist/index.js setup

Then load extension/ at chrome://extensions (Developer mode, Load unpacked). By hand: claude mcp add --scope user agentcursor -- node /abs/path/dist/index.js.

Rust core (not published to npm, brew or curl; build from source):

cd rust && cargo build --release

MCP config: {"mcpServers":{"agentcursor":{"command":"/abs/path/rust/target/release/agentcursor","args":["mcp"]}}}

There is no npm package named agentcursor. Never run npm install agentcursor or npx agentcursor.

The loop

1. Read: read_page (browser) or agentcursor read <app> (computer use). Output is compact text with refs ([12], [d12]).
2. Act by label or ref: click --text Save or click [d12]. Do not guess coordinates.
3. Verify by reading again. Use changes (read --changes) to get only the diff. Take a screenshot only for canvases and custom-drawn UI.