Spawn and orchestrate Cursor Cloud Agents from task templates with dependency resolution, parallel execution, and automatic retries.
npm install -g spawnee
# Initialize a config file
spawnee init
# Edit .spawneerc.json with your API key
# Validate a template
spawnee validate my-tasks.yaml
# Dry run (preview without spawning agents)
spawnee run my-tasks.yaml --dry-run
# Execute the template
spawnee run my-tasks.yaml
spawnee supports three configuration methods with the following priority (highest to lowest):
.spawneerc.json) - Override defaults| Option | CLI Flag | Environment Variable | Config Key | Default |
|---|---|---|---|---|
| API Key | --api-key, -k | SPAWNEE_API_KEY | apiKey | (required) |
| API Base URL | --api-url | SPAWNEE_API_URL | apiBaseUrl | https://api.cursor.com |
| Max Concurrent | --concurrency, -c | SPAWNEE_CONCURRENCY | maxConcurrent | 10 |
| Poll Interval | --poll-interval | SPAWNEE_POLL_INTERVAL | pollInterval | 15000 (ms) |
| Default Timeout | --timeout, -t | SPAWNEE_TIMEOUT | defaultTimeout | 3600000 (ms) |
| State File | --state-file | SPAWNEE_STATE_FILE | stateFile | .spawnee-state.json |
| Config File | --config | SPAWNEE_CONFIG | - | .spawneerc.json |
| Verbose | --verbose, -v | SPAWNEE_VERBOSE | verbose | false |
Create a .spawneerc.json file in your project root:
{
"apiKey": "your-cursor-api-key",
"apiBaseUrl": "https://api.cursor.com",
"maxConcurrent": 10,
"pollInterval": 15000,
"defaultTimeout": 3600000,
"stateFile": ".spawnee-state.json",
"verbose": false
}
Or generate one with:
spawnee init
export SPAWNEE_API_KEY="your-cursor-api-key"
export SPAWNEE_CONCURRENCY=5
export SPAWNEE_TIMEOUT=7200000
export SPAWNEE_VERBOSE=true
spawnee run my-tasks.yaml \
--api-key "your-key" \
--concurrency 5 \
--timeout 7200000 \
--poll-interval 10000 \
--state-file ".my-state.json" \
--verbose
spawnee run <template>Execute a task template.
spawnee run my-tasks.yaml [options]
Options:
-k, --api-key <key> - Cursor API key--api-url <url> - API base URL-c, --concurrency <n> - Max concurrent agents-t, --timeout <ms> - Default task timeout--poll-interval <ms> - Status poll interval--state-file <path> - State file for persistence-d, --dry-run - Preview without spawning agents--no-persist - Disable state persistence--update-source - Update source YAML with task status for resume capability-v, --verbose - Enable verbose outputspawnee validate <template>Validate a task template without running it.
spawnee validate my-tasks.yaml
spawnee statusCheck status of running agents.
spawnee status [options]
Options:
-k, --api-key <key> - Cursor API key--api-url <url> - API base URLspawnee cancel <agent-id>Cancel a running agent.
spawnee cancel abc123def456
spawnee initCreate a .spawneerc.json config file.
spawnee init # Create config file
spawnee init --force # Overwrite existing
spawnee configShow the resolved configuration (useful for debugging).
spawnee config
spawnee modelsList available models from the Cursor API. Use this to see which model IDs are valid for your templates.
spawnee models [options]
Options:
-k, --api-key <key> - Cursor API key--api-url <url> - API base URLTemplates can be JSON or YAML. Here's a complete example:
name: "My Task Plan"
repository:
url: "https://github.com/your-org/your-repo"
branch: "main"
baseBranch: "develop"
defaults:
model: "auto"
timeout: 3600000
retries: 2
context:
instructions: |
You are implementing features for a Node.js application.
Follow existing code patterns and conventions.
files:
- "README.md"
- "package.json"
tasks:
- id: "setup"
name: "Project Setup"
priority: 100
branch: "feature/setup"
prompt: |
Initialize the project structure:
1. Create necessary directories
2. Set up configuration files
- id: "feature-a"
name: "Feature A"
dependsOn: ["setup"]
priority: 80
branch: "feature/a"
prompt: |
Implement Feature A with tests.
files:
- "src/features/"
- id: "feature-b"
name: "Feature B"
dependsOn: ["setup"]
priority: 80
branch: "feature/b"
prompt: |
Implement Feature B with tests.
- id: "integration"
name: "Integration"
dependsOn: ["feature-a", "feature-b"]
priority: 60
branch: "feature/integration"
prompt: |
Integrate features and add integration tests.
validation:
command: "npm test"
successPattern: "passed"
Required fields:
name - Template namerepository.url - GitHub repository URLtasks - Array of tasksTask fields:
id (required) - Unique task identifiername (required) - Human-readable nameprompt (required) - Instructions for the agentdependsOn - Array of task IDs this task depends onpriority - Higher runs first (default: 0)branch - Git branch for the taskfiles - Files to include in contexttimeout - Task-specific timeout (ms)retries - Max retry attemptscomplete - Mark as already complete (skip)status - Task status for resume: pending, started, completed, failedmodel - Override default model for this taskrepository - Override plan-level repository: { url, branch }breakpoint - Pause for human review when task completesvalidation.command - Command to verify completionvalidation.successPattern - Expected output patterndependsOnmaxConcurrent)When tasks depend on each other in the same repository, include instructions in your prompts for agents to pull dependent branches:
tasks:
- id: "base-feature"
name: "Base Feature"
branch: "feature/base"
prompt: |
Implement the base authentication system.
- id: "extended-feature"
name: "Extended Feature"
dependsOn: ["base-feature"]
branch: "feature/extended"
prompt: |
Extend the authentication with OAuth support.
**Before starting:** Pull changes from the `feature/base` branch to get the base authentication code.
spawnee automatically adds dependency context to prompts, including branch names and PR links. For same-repo dependencies, it instructs agents to pull dependent branches.
Tasks can depend on work in different repositories. spawnee will:
tasks:
- id: "api-update"
name: "Update API"
repository:
url: "https://github.com/org/backend"
prompt: "Add new endpoint for user profiles"
- id: "frontend-integration"
name: "Frontend Integration"
dependsOn: ["api-update"]
repository:
url: "https://github.com/org/frontend"
prompt: |
Integrate with the new user profile API endpoint.
Refer to the backend PR for API documentation.
Use "bottleneck" tasks to integrate parallel work and enable human review:
tasks:
# Wave 1: Parallel independent tasks
- id: "feature-a"
name: "Feature A"
prompt: "Implement feature A"
- id: "feature-b"
name: "Feature B"
prompt: "Implement feature B"
- id: "feature-c"
name: "Feature C"
prompt: "Implement feature C"
# Bottleneck: Integrates all Wave 1 work
- id: "integration"
name: "Integration & Review"
dependsOn: ["feature-a", "feature-b", "feature-c"]
breakpoint: true # Pause for human review
prompt: |
Integrate all features from the dependent tasks:
1. Pull all feature branches
2. Resolve any conflicts
3. Ensure all tests pass
4. Create unified documentation
When integration completes, spawnee will pause and prompt you to review before continuing to any tasks that depend on it.
For multi-repo projects, create separate bottleneck tasks for each repository.
Tasks run in parallel when:
Design your task graph for maximum parallelism when tasks don't conflict:
# Good: Independent features run in parallel
tasks:
- id: "docs"
prompt: "Write documentation"
- id: "tests"
prompt: "Add test coverage"
- id: "ci"
prompt: "Set up CI pipeline"
A single agent can perform multiple related tasks. Consider grouping related work:
# Instead of many tiny tasks:
tasks:
- id: "auth-complete"
name: "Complete Auth System"
prompt: |
Implement the complete authentication system:
1. User registration with email verification
2. Login with JWT tokens
3. Password reset flow
4. Session management
Use --update-source to track progress in the YAML file:
spawnee run my-tasks.yaml --update-source
This updates the source YAML with status: started and status: completed fields. If interrupted, re-running the same command will skip completed tasks.
Override plan-level defaults at the task level:
defaults:
model: "auto"
timeout: 3600000
tasks:
- id: "simple-task"
prompt: "Quick formatting fix"
model: "gpt-4o" # Faster model for simple task
timeout: 300000 # 5 min timeout
- id: "complex-task"
prompt: "Architect new microservice"
model: "claude-4.5-opus-high-thinking" # More capable model
timeout: 7200000 # 2 hour timeout
- id: "other-repo-task"
prompt: "Update shared library"
repository:
url: "https://github.com/org/shared-lib"
branch: "develop"
Get your Cursor API key from: Cursor Dashboard → Integrations → User API Keys
MIT
FAQs
Spawn and orchestrate Cursor Cloud Agents from task templates
The npm package spawnee receives a total of 0 weekly downloads. As such, spawnee popularity was classified as not popular.
We found that spawnee demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.