cursor-cloud-agents

Deploy Cursor AI agents to GitHub repos. Automatically write code, generate tests, create documentation, and open PRs using your existing Cursor subscription.

# Cursor Cloud Agents Skill

## ⚡ Quick Reference

Most common commands and patterns:

```bash
# Launch an agent (uses default model: gpt-5.2)
cursor-api.sh launch --repo owner/repo --prompt "Add tests for auth module"

# Check agent status
cursor-api.sh status <agent-id>

# Get conversation history
cursor-api.sh conversation <agent-id>

# Send follow-up message
cursor-api.sh followup <agent-id> --prompt "Also add edge case tests"

# List all agents
cursor-api.sh list

# Check usage/quota
cursor-api.sh usage
```

**Common Options:**
- `--model <name>` - Specify model (default: gpt-5.2)
- `--branch <name>` - Target branch
- `--no-pr` - Don't auto-create PR
- `--no-cache` - Bypass cache
- `--verbose` - Debug output
- `--background` - Run agent in background mode

**Background Tasks:**
```bash
cursor-api.sh launch --repo owner/repo --prompt "..." --background
cursor-api.sh bg-list
cursor-api.sh bg-status <task-id>
cursor-api.sh bg-logs <task-id>
```

**Max Runtime (Background Tasks):**
```bash
# Default is 24 hours
 cursor-api.sh launch --repo owner/repo --prompt "..." --background

# Custom max runtime (2 hours)
cursor-api.sh launch --repo owner/repo --prompt "..." --background --max-runtime 7200

# Unlimited runtime (not recommended)
cursor-api.sh launch --repo owner/repo --prompt "..." --background --max-runtime 0

# Set default via environment variable
export CURSOR_BG_MAX_RUNTIME=43200  # 12 hours
cursor-api.sh launch --repo owner/repo --prompt "..." --background
```

**Short Commands (cca aliases):**

For faster daily usage, source the cca-aliases.sh file:
```bash
source scripts/cca-aliases.sh
```

Then use `cca` instead of `cursor-api.sh`:
```bash
cca list                    # List agents
cca launch --repo ...       # Launch agent
cca status <id>             # Check status
cca conversation <id>       # Get conversation
cca followup <id> --prompt  # Send followup
cca delete <id>             # Delete agent
```

**Exit Codes:** 0=Success, 1=API Error, 2=Auth, 3=Rate Limit, 4=Repo Access, 5=Invalid Args

---

## Overview

This skill wraps the Cursor Cloud Agents HTTP API, allowing OpenClaw to dispatch coding tasks to Cursor's cloud agents, monitor their progress, and incorporate results.

### When to Use

Use this skill when you need to:

- Delegate coding tasks to Cursor agents running on GitHub repositories
- Generate code, tests, or documentation on existing codebases
- Perform refactoring or feature implementation asynchronously
- Get a "second opinion" on code changes

### When NOT to Use

- For simple questions that don't require code changes
- When you need real-time streaming responses (use local Cursor CLI instead)
- For tasks outside of GitHub repositories

## Authentication

The skill automatically discovers your Cursor API key from these locations (in order):

1. **Environment variable:** `CURSOR_API_KEY`
2. **OpenClaw env file:** `~/.openclaw/.env`
3. **OpenClaw local env:** `~/.openclaw/.env.local`
4. **Project env:** `.env` in current directory
5. **Cursor config:** `~/.cursor/config.json`

**Recommended:** Add to `~/.openclaw/.env`:
```bash
CURSOR_API_KEY=your_cursor_api_key_here
```

To get your API key:
1. Open Cursor IDE
2. Go to Settings → General
3. Copy your API key

**Verify it's working:**
```bash
cursor-api.sh me
```

## Workflow Patterns

### Pattern A: Fire-and-Forget

Launch an agent and let it work independently. Check back later.

```bash
# Launch agent (uses default model: gpt-5.2)
cursor-api.sh launch --repo owner/repo --prompt "Add comprehensive tests for auth module"

# Launch with specific model
cursor-api.sh launch --repo owner/repo --prompt "Add tests" --model claude-4-opus

# Response: {"id": "agent_123", "status": "CREATING", ...}

# Later - check status
cursor-api.sh status agent_123
```

**Note:** If no `--model` is specified, the default model (`gpt-5.2`) will be used automatically. You'll see a message indicating which model is being used.

**Best for:** Tasks that don't need immediate attention, exploratory work

### Pattern B: Supervised Dispatch

Launch, monitor, and report results when complete.

```bash
# 1. Launch
cursor-api.sh launch --repo owner/repo --prompt "Implement user authentication"

# 2. Poll for completion (check every 60 seconds)
while true; do
    status=$(cursor-api.sh status agent_123)
    if [[ $(echo "$status" | jq -r '.status') == "FINISHED" ]]; then
        break
    fi
    sleep 60
done

# 3. Get results
cursor-api.sh conversation agent_123 | jq -r '.messages[] | select(.role == "assistant") | .content'
```

**Best for:** Important tasks where you want to report completion

### Pattern C: Iterative Collaboration

Launch, review, and send follow-ups to refine work.

```bash
# 1. Launch initial task
cursor-api.sh launch --repo owner/repo --prompt "Add login page"

# 2. Review conversation
cursor-api.sh conversation agent_123

# 3. Send follow-up
cursor-api.sh followup agent_123 --prompt "Also add form validation and error handling"

# 4. Final review when done
cursor-api.sh conversation agent_123
```

**Best for:** Complex tasks requiring multiple iterations

### Pattern D: Background Mode

For long-running tasks, launch agents in background mode and check on them later.

```bash
# Launch in background
result=$(cursor-api.sh launch --repo owner/repo --prompt "Refactor entire codebase" --background)
task_id=$(echo "$result" | jq -r '.background_task_id')
echo "Task started: $task_id"

# List active background tasks
cursor-api.sh bg-list

# Check specific task status
cursor-api.sh bg-status $task_id

# View logs
cursor-api.sh bg-logs $task_id

# List all tasks including completed ones
cursor-api.sh bg-list --all
```

Background tasks are monitored automatically and logs are saved to `~/.cache/cursor-api/background-tasks/`.

**Best for:** Long-running tasks (10+ minutes), batch operations, CI/CD integration

## Commands Reference

### List Agents

```bash
cursor-api.sh list
```

Returns all agents with status, repo, and creation time.

### Launch Agent

```bash
cursor-api.sh launch --repo owner/repo --prompt "Your task description" [--model model-name] [--branch branch-name] [--no-pr] [--background]
```

Options:
- `--repo` (required): Repository in `owner/repo` format
- `--prompt` (required): Initial instructions for the agent
- `--model` (optional): Model to use (defaults to `gpt-5.2` if not specified)
- `--branch` (optional): Target branch name (auto-generated if omitted)
- `--no-pr` (optional): Don't auto-create a PR
- `--background` (optional): Run agent in background mode

**Note:** When launched without `--model`, the skill automatically uses `gpt-5.2` and displays a message indicating which model is being used.

**Background Mode:** When using `--background`, the command returns immediately with a `background_task_id`. Use `bg-list`, `bg-status`, and `bg-logs` to monitor progress.

### Check Status

```bash
cursor-api.sh status <agent-id>
```

Returns:
- `status`: CREATING, RUNNING, FINISHED, STOPPED, ERROR
- `summary`: Summary of work done (if finished)
- `prUrl`: URL to created PR (if any)

### Get Conversation

```bash
cursor-api.sh conversation <agent-id>
```

Returns full message history including all prompts and responses.

### Send Follow-up

```bash
cursor-api.sh followup <agent-id> --prompt "Additional instructions"
```

Resumes a stopped or finished agent with new instructions.

### Stop Agent

```bash
cursor-api.sh stop <agent-id>
```

Stops a running agent gracefully.

### Delete Agent

```bash
cursor-api.sh delete <agent-id>
```

Permanently deletes an agent and its conversation history.

### List Models

```bash
cursor-api.sh models
```

Returns available models for agent tasks.

### Account Info

```bash
cursor-api.sh me
```

Returns account information including subscription tier.

### Verify Repository

```bash
cursor-api.sh verify owner/repo
```

Checks if the specified repository is accessible by Cursor agents.

Exit code 4 if repository not accessible.

###