Name: cloud-agent
Author: ZenRay

Prompt file imported from ZenRay/CursorTemplate (.cursor/commands/cloud-agent.md). Copyright stays with the author.

/cloud-agent — Background & Cloud Agents

Launch and manage Cloud Agents for long-running or asynchronous tasks.

What are Cloud Agents?

Cloud Agents (formerly Background Agents) run in Cursor's cloud environment:

Continue working when local machine is off
Run on separate git branches
Notify when complete
Ideal for long-running tasks

When to Use

Scenario	Local Agent	Cloud Agent
Quick edits (< 5 min)	✅	❌ Overkill
Medium tasks (5-30 min)	✅	✅ Either
Long tasks (30+ min)	❌ Blocks IDE	✅ Recommended
Overnight processing	❌	✅ Essential
Multi-branch work	❌	✅ Parallel

Commands

Launch Cloud Agent

/cloud-agent launch "Refactor authentication system"

Options:

--branch feature/auth-refactor - Specific branch
--worktree - Use git worktree isolation
--notify - Notify on completion

List Running Agents

/cloud-agent list

Output:

## Cloud Agents

| ID | Task | Branch | Status | Runtime |
|----|------|--------|--------|---------|
| ca-123 | Auth refactor | feature/auth | Running | 45 min |
| ca-124 | API migration | feature/api | Complete | 2 hrs |

Check Status

/cloud-agent status ca-123

Shows:

Current progress
Files modified
Commits made
Any blockers

Get Results

/cloud-agent results ca-124

Downloads:

Changed files
Commit history
Summary report

Cancel Agent

/cloud-agent cancel ca-123

Best Practices

Task Preparation

Clear scope - Define what needs to be done
Test strategy - How to verify results
Rollback plan - If results are unsatisfactory

Example: Large Refactor

/cloud-agent launch "Migrate all API routes to new middleware pattern"

Task details:
- Update 50 route files
- Migrate auth middleware
- Update tests
- Verify no breaking changes

Options:
--branch feature/middleware-migration
--worktree
--notify slack/email

Monitoring

Check periodically:

/cloud-agent status ca-123

Or wait for notification.

Worktree Mode

Creates isolated git worktree:

main branch:    working on feature X
worktree:       cloud agent working on feature Y

Benefits:

No interference with local work
Clean separation
Easy to discard if needed

Integration with Workflow

Plan Mode → Cloud Agent

1. /plan "Design new architecture"
2. Review plan locally
3. /cloud-agent launch "Implement architecture"
4. Continue local work
5. Review results when notified

Parallel Development

Local Agent:    Working on UI components
Cloud Agent 1:  Refactoring backend API
Cloud Agent 2:  Updating documentation

Cost Considerations

Cloud Agents use Cursor usage credits
Longer tasks = more credits
Monitor usage in Settings

Troubleshooting

Agent Stuck

/cloud-agent status ca-123
→ Check for input requests or errors

Agent Failed

/cloud-agent logs ca-123
→ Review error messages
→ Relaunch if needed

Results Not As Expected

1. Review changes in worktree
2. Cherry-pick desired changes
3. Discard unwanted changes
4. Relaunch with clearer instructions

Security

Cloud Agents run in isolated environments
No access to local secrets
Git credentials handled securely
Changes only in designated branches

Install cloud-agent and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# /cloud-agent — Background & Cloud Agents Launch and manage Cloud Agents for long-running or asynchronous tasks. ## What are Cloud Agents? Cloud Agents (formerly Background Agents) run in Cursor's cloud environment: - Continue working when local machine is off - Run on separate git branches - Notify when complete - Ideal for long-running tasks ## When to Use | Scenario | Local Agent | Cloud Agent | |----------|-------------|-------------| | Quick edits (< 5 min) | ✅ | ❌ Overkill | | Medium tasks (5-30 min) | ✅ | ✅ Either | | Long tasks (30+ min) | ❌ Blocks IDE | ✅ Recommended | | Overnight processing | ❌ | ✅ Essential | | Multi-branch work | ❌ | ✅ Parallel | ## Commands ### Launch Cloud Agent ``` /cloud-agent launch "Refactor authentication system" ``` Options: - `--branch feature/auth-refactor` - Specific branch - `--worktree` - Use git worktree isolation - `--notify` - Notify on completion ### List Running Agents ``` /cloud-agent list ``` Output: ``` ## Cloud Agents | ID | Task | Branch | Status | Runtime | |----|------|--------|--------|---------| | ca-123 | Auth refactor | feature/auth | Running | 45 min | | ca-124 | API migration | feature/api | Complete | 2 hrs | ``` ### Check Status ``` /cloud-agent status ca-123 ``` Shows: - Current progress - Files modified - Commits made - Any blockers ### Get Results ``` /cloud-agent results ca-124 ``` Downloads: - Changed files - Commit history - Summary report ### Cancel Agent ``` /cloud-agent cancel ca-123 ``` ## Best Practices ### Task Preparation 1. **Clear scope** - Define what needs to be done 2. **Test strategy** - How to verify results 3. **Rollback plan** - If results are unsatisfactory ### Example: Large Refactor ``` /cloud-agent launch "Migrate all API routes to new middleware pattern" Task details: - Update 50 route files - Migrate auth middleware - Update tests - Verify no breaking changes Options: --branch feature/middleware-migration --worktree --notify slack/email ``` ### Monitoring Check periodically: ``` /cloud-agent status ca-123 ``` Or wait for notification. ## Worktree Mode Creates isolated git worktree: ``` main branch: working on feature X worktree: cloud agent working on feature Y ``` Benefits: - No interference with local work - Clean separation - Easy to discard if needed ## Integration with Workflow ### Plan Mode → Cloud Agent ``` 1. /plan "Design new architecture" 2. Review plan locally 3. /cloud-agent launch "Implement architecture" 4. Continue local work 5. Review results when notified ``` ### Parallel Development ``` Local Agent: Working on UI components Cloud Agent 1: Refactoring backend API Cloud Agent 2: Updating documentation ``` ## Cost Considerations - Cloud Agents use Cursor usage credits - Longer tasks = more credits - Monitor usage in Settings ## Troubleshooting ### Agent Stuck ``` /cloud-agent status ca-123 → Check for input requests or errors ``` ### Agent Failed ``` /cloud-agent logs ca-123 → Review error messages → Relaunch if needed ``` ### Results Not As Expected ``` 1. Review changes in worktree 2. Cherry-pick desired changes 3. Discard unwanted changes 4. Relaunch with clearer instructions ``` ## Security - Cloud Agents run in isolated environments - No access to local secrets - Git credentials handled securely - Changes only in designated branches

{ "prompt": "# /cloud-agent — Background & Cloud Agents\n\nLaunch and manage Cloud Agents for long-running or asynchronous tasks.\n\n## What are Cloud Agents?\n\nCloud Agents (formerly Background Agents) run in Cursor's cloud environment:\n- Continue working when local machine is off\n- Run on separate git branches\n- Notify when complete\n- Ideal for long-running tasks\n\n## When to Use\n\n| Scenario | Local Agent | Cloud Agent |\n|----------|-------------|-------------|\n| Quick edits (< 5 min) | ✅ | ❌ Overkill |\n| Medium tasks (5-30 min) | ✅ | ✅ Either |\n| Long tasks (30+ min) | ❌ Blocks IDE | ✅ Recommended |\n| Overnight processing | ❌ | ✅ Essential |\n| Multi-branch work | ❌ | ✅ Parallel |\n\n## Commands\n\n### Launch Cloud Agent\n\n```\n/cloud-agent launch \"Refactor authentication system\"\n```\n\nOptions:\n- `--branch feature/auth-refactor` - Specific branch\n- `--worktree` - Use git worktree isolation\n- `--notify` - Notify on completion\n\n### List Running Agents\n\n```\n/cloud-agent list\n```\n\nOutput:\n```\n## Cloud Agents\n\n| ID | Task | Branch | Status | Runtime |\n|----|------|--------|--------|---------|\n| ca-123 | Auth refactor | feature/auth | Running | 45 min |\n| ca-124 | API migration | feature/api | Complete | 2 hrs |\n```\n\n### Check Status\n\n```\n/cloud-agent status ca-123\n```\n\nShows:\n- Current progress\n- Files modified\n- Commits made\n- Any blockers\n\n### Get Results\n\n```\n/cloud-agent results ca-124\n```\n\nDownloads:\n- Changed files\n- Commit history\n- Summary report\n\n### Cancel Agent\n\n```\n/cloud-agent cancel ca-123\n```\n\n## Best Practices\n\n### Task Preparation\n\n1. **Clear scope** - Define what needs to be done\n2. **Test strategy** - How to verify results\n3. **Rollback plan** - If results are unsatisfactory\n\n### Example: Large Refactor\n\n```\n/cloud-agent launch \"Migrate all API routes to new middleware pattern\"\n\nTask details:\n- Update 50 route files\n- Migrate auth middleware\n- Update tests\n- Verify no breaking changes\n\nOptions:\n--branch feature/middleware-migration\n--worktree\n--notify slack/email\n```\n\n### Monitoring\n\nCheck periodically:\n```\n/cloud-agent status ca-123\n```\n\nOr wait for notification.\n\n## Worktree Mode\n\nCreates isolated git worktree:\n\n```\nmain branch: working on feature X\nworktree: cloud agent working on feature Y\n```\n\nBenefits:\n- No interference with local work\n- Clean separation\n- Easy to discard if needed\n\n## Integration with Workflow\n\n### Plan Mode → Cloud Agent\n\n```\n1. /plan \"Design new architecture\"\n2. Review plan locally\n3. /cloud-agent launch \"Implement architecture\"\n4. Continue local work\n5. Review results when notified\n```\n\n### Parallel Development\n\n```\nLocal Agent: Working on UI components\nCloud Agent 1: Refactoring backend API\nCloud Agent 2: Updating documentation\n```\n\n## Cost Considerations\n\n- Cloud Agents use Cursor usage credits\n- Longer tasks = more credits\n- Monitor usage in Settings\n\n## Troubleshooting\n\n### Agent Stuck\n```\n/cloud-agent status ca-123\n→ Check for input requests or errors\n```\n\n### Agent Failed\n```\n/cloud-agent logs ca-123\n→ Review error messages\n→ Relaunch if needed\n```\n\n### Results Not As Expected\n```\n1. Review changes in worktree\n2. Cherry-pick desired changes\n3. Discard unwanted changes\n4. Relaunch with clearer instructions\n```\n\n## Security\n\n- Cloud Agents run in isolated environments\n- No access to local secrets\n- Git credentials handled securely\n- Changes only in designated branches", "variables": [], "notes": "Launch and manage Background/Cloud Agents for long-running tasks", "metadata": { "source": { "provider": "github-cursor-commands", "repository": "https://github.com/ZenRay/CursorTemplate", "path": ".cursor/commands/cloud-agent.md", "ref": "0643e2b5863ee982562d545a9276c08523c183b8", "url": "https://github.com/ZenRay/CursorTemplate/blob/0643e2b5863ee982562d545a9276c08523c183b8/.cursor/commands/cloud-agent.md", "key": "ZenRay/CursorTemplate/.cursor/commands/cloud-agent.md" } } }

cloud-agent

About