Cursor Agent Skill

Execute coding tasks using Cursor CLI (agent command). Supports multiple frontier models (GPT-5, Claude Opus/Sonnet, Gemini, Grok, etc.).

⚠️ PTY Mode Required!

Cursor Agent is an interactive terminal application that requires PTY to work correctly.

# ✅ Correct
bash pty:true command:"agent 'Your prompt'"

# ❌ Wrong - will hang without PTY
bash command:"agent 'Your prompt'"

Bash Tool Parameters

| Parameter | Type | Description | | ------------ | ------- | ----------------------------------------------------- | | command | string | Shell command to execute | | pty | boolean | Required! Allocates pseudo-terminal for interactive CLIs | | workdir | string | Working directory (agent only sees this folder's context) | | background | boolean | Run in background, returns sessionId for monitoring | | timeout | number | Timeout in seconds (kills process on expiry) | | elevated | boolean | Run on host instead of sandbox (if allowed) |

Quick Start

# Check status and login
agent status
agent login

# List available models
agent --list-models

# Quick task (interactive mode)
bash pty:true command:"agent 'Add error handling to the API calls'"

# Specify working directory
bash pty:true workdir:~/Projects/myproject command:"agent 'Build a snake game'"

The Pattern: workdir + background + pty

For longer tasks, use background mode:

# Start background task
bash pty:true workdir:~/project background:true command:"agent --yolo 'Refactor the auth module'"

# Returns sessionId, monitor with process tool
process action:list
process action:log sessionId:XXX
process action:poll sessionId:XXX

# Send input
process action:submit sessionId:XXX data:"yes"

# Terminate
process action:kill sessionId:XXX

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

Command Flags Reference

| Flag | Description | |------|-------------| | prompt | Initial prompt for the agent | | --yolo / --force | Auto-approve all operations (dangerous but fast) | | --model <model> | Specify model (gpt-5, sonnet-4, opus-4, gemini, grok, etc.) | | --workspace <path> | Working directory | | -w, --worktree [name] | Run in isolated git worktree | | --print | Non-interactive mode, output to console | | --mode <mode> | Execution mode: plan (read-only planning), ask (Q&A) | | --plan | Plan mode (read-only, no file modifications) | | --cloud | Cloud mode | | --resume | Resume previous session | | --trust | Trust workspace (headless mode only) |

Execution Modes

Interactive Mode (default)

bash pty:true workdir:~/project command:"agent 'Build a dark mode toggle'"

Auto-Execute Mode (--yolo)

# Auto-approve all operations, fast execution
bash pty:true workdir:~/project command:"agent --yolo 'Refactor the auth module'"

Plan Mode (--plan)

# Read-only mode, generate plan without executing
bash pty:true workdir:~/project command:"agent --plan 'Analyze the codebase structure'"

Ask Mode (--mode ask)

# Q&A only, no file modifications
bash pty:true command:"agent --mode ask 'Explain how the auth flow works'"

Non-Interactive Mode (--print) ⭐ Unique Feature

Cursor's unique --print mode, ideal for scripting and CI/CD:

# Non-interactive execution, output to console
bash pty:true command:"agent --print 'Generate a summary of the codebase'"

# JSON output (ideal for parsing)
bash pty:true command:"agent --print --output-format json 'List all API endpoints'"

# Streaming JSON (real-time processing)
bash pty:true command:"agent --print --output-format stream-json 'Analyze the project'"

Use cases:

CI/CD integration
Automation scripts
Batch tasks
Scenarios requiring parsed results

Git Worktree Isolation

For parallel processing of multiple independent tasks:

# Run in isolated worktree
bash pty:true workdir:~/project command:"agent -w fix-issue-78 'Fix the login bug'"

# Specify base branch
bash pty:true workdir:~/project command:"agent -w feature-x --worktree-base develop 'Add feature X'"

Parallel Issue Fixing

Use git worktrees to fix multiple issues simultaneously:

# 1. Create worktrees for each issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. Launch agent in each worktree (background + PTY)
bash pty:true workdir:/tmp/issue-78 background:true command:"agent --yolo 'Fix issue #78: login bug. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"agent --yolo 'Fix issue #99: API timeout. Commit and push.'"

# 3. Monitor progress
process action:list
process action:log sessionId:XXX

# 4. Create PRs
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

Batch PR Reviews

⚠️ NEVER review PRs in OpenClaw's own project directory!

# Clone to temp directory
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130

# Review in plan mode (read-only)
bash pty:true workdir:$REVIEW_DIR command:"agent --plan 'Review this PR for security issues and code quality'"

# Cleanup
trash $REVIEW_DIR

Batch Review Multiple PRs

# Fetch all PR refs
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Launch multiple agents in parallel
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor
process action:list

# Post results to GitHub
gh pr comment 86 --body "<review content>"

Process Tool (Background Task Management)

| Action | Description | |--------|-------------| | list | List all running sessions | | poll | Check if session is still running | | log | Get session output (supports offset/limit) | | write | Send raw data to stdin | | submit | Send data + newline (simulate Enter) | | send-keys | Send key presses | | paste | Paste text | | kill | Terminate session |

Model Selection

# List available models
agent --list-models

# Specify model
bash pty:true command:"agent --model opus-4 'Complex refactoring task'"
bash pty:true command:"agent --model gpt-5 'Build a CLI tool'"
bash pty:true command:"agent --model gemini 'Analyze this Python codebase'"

Auto-Notify on Completion

For long-running tasks, append a wake trigger to your prompt:

bash pty:true workdir:~/project background:true command:"agent --yolo 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API\" --mode now'"

This triggers immediate notification instead of waiting for heartbeat.

Authentication

# Check login status
agent status

# Login
agent login

# Logout
agent logout

# View account info
agent about

⚠️ Rules

Always use pty:true - Will hang without PTY
Use background for long tasks - Don't block main thread
--yolo for building - Auto-approve changes
--plan for reviewing - Read-only analysis
--print for scripting - Non-interactive, parseable output
Use -w worktree for isolation - Parallel task processing
NEVER start in ~/.openclaw/ - It'll read your soul docs!
Notify user on completion - Don't leave user guessing

Progress Updates

When spawning background agents:

Send 1 short message stating what's running
Only update when something changes:
- Milestone completed
- User input needed
- Error or user action required
- Task finished (explain what changed)

Learnings

PTY is essential: Without pty:true, interactive agents hang or output garbage.
--print is powerful: Cursor's unique non-interactive mode, ideal for CI/CD and scripted tasks.
--plan for safety: When unsure what the agent will do, use --plan first.
worktree for parallel: For multiple independent tasks, worktree isolation is the best choice.
submit vs write: submit sends data + Enter, write sends raw data only.