Cursor Resources

# Cloud Agents

Manage Cursor Cloud Agents through the REST API at `https://api.cursor.com/v0`.

## Prerequisites

- `CURSOR_API_KEY` environment variable must be set
- `jq` must be installed (used by the helper script)
- If the key is not set, ask the user to provide it or set it: `export CURSOR_API_KEY=<key>`
- Keys are created at https://cursor.com/settings

## Inferring the Repository

When the user does not specify a repo URL, infer it from the current working directory:

```bash
git remote get-url origin
```

This gives you the GitHub URL to pass to `launch`. Also infer the current branch with `git branch --show-current` to use as the `ref` unless the user specifies otherwise.

## Branch Confirmation

Before launching an agent, check the current branch with `git branch --show-current`. If the current branch is **not** `main`, pause and ask the user whether they want to branch off of `main` or the current branch. Do this before any other action. Use their answer as the `ref` argument when launching.

## Error Handling

If any step fails (API call, git operation, image encoding, etc.), do not attempt to automatically fix or retry. Instead, clearly report the error to the user: what command failed, the error message, and suggest what they can do about it. Let the user decide the next step.

## Helper Script

All API calls go through `scripts/cloud-agent.sh` (relative to this skill directory). Execute it via the Shell tool.

```bash
SKILL_DIR="$HOME/.cursor/skills/cloud-agents"
"$SKILL_DIR/scripts/cloud-agent.sh" <command> [args...]
```

## Commands Reference

### List agents

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" list          # default 20
"$SKILL_DIR/scripts/cloud-agent.sh" list 50        # up to 100
```

Pipe through jq for readable output:

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" list | jq '.agents[] | {id, name, status, branch: .target.branchName, pr: .target.prUrl}'
```

### Check agent status

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq .
```

Statuses: `CREATING`, `RUNNING`, `FINISHED`, `STOPPED`, `ERROR`

### Get conversation history

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" conversation <agent_id> | jq '.messages[] | {type, text}'
```

### Launch a new agent

Takes two positional args (repo, prompt) and optional flags:

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Your prompt here" \
  --ref main \
  --pr \
  --branch "my-branch"
```

Flags:
- `--ref <ref>` - source ref (default: main)
- `--pr` - auto-create a PR when done
- `--model <model>` - model to use
- `--branch <name>` - custom branch name
- `--image <path>` - attach an image (repeatable, max 5)

### Launch agent on an existing PR

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" launch-pr \
  "https://github.com/org/repo/pull/123" \
  "Fix the failing tests"
```

Flags:
- `--no-auto-branch` - disable auto-branch creation
- `--model <model>` - model to use
- `--image <path>` - attach an image (repeatable, max 5)

### Send follow-up

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> "Also add tests"
```

Flags:
- `--image <path>` - attach an image (repeatable, max 5)

### Attaching images

Use `--image <path>` on `launch`, `launch-pr`, or `followup`. Repeat for multiple images (max 5). The script base64-encodes them and extracts dimensions via `sips`.

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Implement this design" \
  --ref main \
  --image /path/to/mockup.png \
  --image /path/to/reference.jpg
```

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> \
  "The button should look like this instead" \
  --image /path/to/screenshot.png
```

When the user attaches an image in the conversation, resolve its absolute file path and pass it with `--image`.

### Poll agent

Monitors a running agent with adaptive intervals until it reaches a terminal state. Run in the background with `block_until_ms: 0`, then read the terminal file to check progress.

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" poll <agent_id>        # default 30m timeout
"$SKILL_DIR/scripts/cloud-agent.sh" poll <agent_id> 10     # 10m timeout
```

Adaptive intervals: 15s for the first 2 minutes, 30s for 2-5 minutes, 60s after 5 minutes.

Exit codes: `0` = FINISHED, `1` = ERROR, `2` = STOPPED, `3` = TIMEOUT.

Output format:

```
Polling agent bc-abc123 (timeout: 30m)
[0m 15s] RUNNING | 3 messages (1 new)
  > "I'll start by reading the relevant files..."
[0m 30s] RUNNING | 5 messages (2 new)
  > "Now updating the component..."
  > "Let me fix the TypeScript error..."
[1m 00s] RUNNING (no new messages)
[2m 30s] FINISHED | 8 messages (1 new)
  > "All changes committed and pushed. Summary: ..."
```

### Apply agent changes

Fetches the agent's branch and squash-merges all its changes into a single commit on the current branch. Requires a clean working tree.

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" apply <agent_id>
```

The commit message includes the agent name, ID, and branch for traceability. If there are merge conflicts, git will report them and the command will exit -- resolve conflicts manually, then `git commit`.

### Stop / Delete

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" stop <agent_id>
"$SKILL_DIR/scripts/cloud-agent.sh" delete <agent_id>
```

### Utility

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" me       # API key info
"$SKILL_DIR/scripts/cloud-agent.sh" models   # available models
"$SKILL_DIR/scripts/cloud-agent.sh" repos    # accessible GitHub repos (rate-limited: 1/min)
```

## Pulling Agent Changes Locally

After an agent finishes (or while it's running), pull its changes into the local repo.

### Step 1: Get the agent's branch name

```bash
BRANCH=$("$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq -r '.target.branchName')
```

### Step 2: Fetch and checkout

```bash
git fetch --all
git checkout "$BRANCH"
git pull origin "$BRANCH"
```

### Step 3: Cherry-pick onto current branch (alternative)

If the user wants to apply agent commits onto their current branch instead of switching:

```bash
git fetch --all
CURRENT=$(git branch --show-current)

# Find commits the agent made (commits on agent branch not on current)
COMMITS=$(git log --oneline "$CURRENT".."origin/$BRANCH" --reverse --format='%H')

for commit in $COMMITS; do
  git cherry-pick "$commit"
done
```

### Step 4: Merge (alternative)

```bash
git fetch --all
git merge "origin/$BRANCH"
```

### Step 5: Diff review

```bash
git fetch --all
git diff HEAD..."origin/$BRANCH"
```

## Workflow: Launch and Monitor

1. Launch the agent
2. Start polling in the background:

```bash
"$SKILL_DIR/scripts/cloud-agent.sh" poll <agent_id>
```

Run this with `block_until_ms: 0` so it streams to a terminal file. Read the terminal file periodically to check progress and relay updates to the user.

3. When the poll exits:
   - Exit code `0` (FINISHED): show summary and ask user how to apply changes (checkout / cherry-pick / merge)
   - Exit code `1` (ERROR): fetch full conversation to diagnose
   - Exit code `2` (STOPPED): inform the user
   - Exit code `3` (TIMEOUT): inform the user, offer to continue polling or stop the agent

## Workflow: Review Running Agents

1. List agents, filter by `RUNNING` status
2. For each, show id, name, branch, time since creation
3. Offer to check conversation, send follow-up, or stop