Cursor Agent Skill

Two ways to use Cursor Agent from OpenClaw, for different scenarios.

Related

• OpenClaw Node for VS Code — VS Code/Cursor extension that enables the Node path (install this first for Path 2)
• vscode-node — Standalone skill for the Node path only (if you don't need Cursor CLI)
• Source: github.com/xiaoyaner-home/openclaw-vscode

Path Selection

Default: CLI. Use Node only when you specifically need IDE intelligence.

Path 1: CLI (Local Cursor Agent)

Prerequisites

# Install
curl https://cursor.com/install -fsS | bash

# Login
agent login

# Verify
agent --version

Modes

Interactive Mode

# Start interactive session
agent

# Start with prompt
agent "refactor the auth module to use JWT tokens"

# Start in plan mode
agent --plan "design a caching layer for the API"

# Start in ask mode
agent --mode=ask "explain how the auth middleware works"

Non-Interactive Mode (Automation)

# One-shot task (prints result, exits)
agent -p "find and fix all unused imports in src/"

# With specific model
agent -p "review this code for security issues" --model gpt-5.2

# JSON output for parsing
agent -p "list all TODO comments" --output-format json

# Streaming JSON (real-time)
agent -p "run tests and report" --output-format stream-json --stream-partial-output

# Force mode (auto-apply changes, no confirmation)
agent -p "fix all linting errors" --force

Cloud Agent Handoff

Push work to Cursor's cloud to continue running while you're away:

# Start directly in cloud
agent -c "refactor the auth module and add comprehensive tests"

# Mid-conversation: prepend & to send to cloud
& refactor the auth module and add comprehensive tests

Pick up at cursor.com/agents.

Session Management

agent ls              # List previous conversations
agent resume          # Resume most recent
agent --continue      # Continue previous session
agent --resume="id"   # Resume specific conversation

Slash Commands (Interactive)

Keyboard Shortcuts

Context & Rules

The CLI automatically loads:

• .cursor/rules directory
• AGENTS.md at project root
• CLAUDE.md at project root
• MCP servers from mcp.json

Use @filename or @directory/ in interactive mode to include context.

⚠️ Using CLI from OpenClaw (PTY Required)

Cursor CLI is an interactive TUI — it needs a real terminal. Use pty:true:

# ✅ Correct — with PTY
exec pty:true command:"agent -p 'Your task'" workdir:/path/to/project

# ✅ Background for longer tasks
exec pty:true background:true command:"agent -p 'Build REST API'" workdir:/path/to/project

# ❌ Wrong — will hang
exec command:"agent -p 'Your task'"

For long tasks, use background + poll:

# Start
exec pty:true background:true workdir:~/project command:"agent -p 'Add comprehensive tests for the auth module' --force"

# Check progress
process action:log sessionId:XXX

# Check if done
process action:poll sessionId:XXX

Sandbox Controls

# Start with sandbox enabled
agent --sandbox enabled

# Start with sandbox disabled
agent --sandbox disabled

# Configure interactively
/sandbox

Sandbox supports granular network access controls — define which domains the agent can reach.

Path 2: VS Code / Cursor Node

Remote-control a Cursor/VS Code IDE through the OpenClaw Node protocol. The IDE must have the openclaw-node-vscode extension installed and connected.

Prerequisites

• Extension installed: VS Code Marketplace
• Node visible in nodes status
• Extension status bar shows 🟢

Invocation Pattern

nodes invoke --node "\x3Cname>" --invokeCommand "\x3Ccmd>" --invokeParamsJson '{"key":"val"}'

Timeout Guide

Command Reference

Quick Examples

# Read a file
nodes invoke --node "my-cursor" --invokeCommand "vscode.file.read" \
  --invokeParamsJson '{"path":"src/main.ts"}'

# Get diagnostics (real type errors!)
nodes invoke --node "my-cursor" --invokeCommand "vscode.diagnostics.get"

# Go to definition
nodes invoke --node "my-cursor" --invokeCommand "vscode.lang.definition" \
  --invokeParamsJson '{"path":"src/main.ts","line":10,"character":5}'

# Git status + commit
nodes invoke --node "my-cursor" --invokeCommand "vscode.git.status"
nodes invoke --node "my-cursor" --invokeCommand "vscode.git.stage" \
  --invokeParamsJson '{"paths":["src/main.ts"]}'
nodes invoke --node "my-cursor" --invokeCommand "vscode.git.commit" \
  --invokeParamsJson '{"message":"fix: resolve type error"}'

# Delegate to Cursor Agent (through IDE)
nodes invoke --node "my-cursor" --invokeCommand "vscode.agent.run" \
  --invokeParamsJson '{"prompt":"Add error handling to all API endpoints","mode":"plan"}' \
  --invokeTimeoutMs 180000

Node Workflow: Fix → Verify → Commit

The real power of Node path — a closed loop with IDE intelligence:

1. diagnostics.get           → Find real errors
2. vscode.agent.run (fix)    → Let Cursor Agent fix them
3. diagnostics.get           → Verify errors resolved
4. test.run                  → Run tests
5. test.results              → Check results
6. git.diff                  → Review changes
7. git.stage + git.commit    → Ship it

No tmux, no TTY hacks — all through VS Code API.

Combined Workflow Example

Use CLI for broad tasks, switch to Node for precision:

1. CLI: agent -p "implement user authentication module" --force
   → Generates the initial code quickly

2. Node: vscode.diagnostics.get
   → Reveals 3 type errors the CLI missed

3. Node: vscode.agent.run '{"prompt":"fix these type errors: ..."}'
   → Fixes with full IDE context

4. Node: vscode.test.run
   → Runs test suite

5. Node: vscode.git.stage + vscode.git.commit
   → Clean commit

Error Handling

Security

• CLI: Respects sandbox mode, command approval, rules
• Node: All paths relative to workspace, Ed25519 device identity, Gateway approval required
• Both: No raw shell access by default