Workflow Parallel Agents

Parallel Agents & Worktrees

Degree of freedom: MIXED. What to split and which model [HIGH freedom]; isolated worktrees and no shared-file writes [LOW freedom — run exactly].

How to reason

1. Observe — independent tasks vs one shared file
2. Interpret — worktree / cloud / best-of-N
3. Classify — parallel-safe / must-serialize
4. Severity — two agents editing one path is a conflict, not speed

Worked example

Observe: "fix tests" and "write the README" touch different trees. Interpret: two worktrees, two agents. Classify: parallel-safe; do not also give both package.json. Merge: integrate one result at a time; compare best-of-N on the same prompt.

Self-critique before reporting

• Isolation — no two agents owned the same files
• Prompt named — each delegate had a concrete done-check
• Compared if best-of-N — a winner was picked with a reason
• Right owner — one sequential feature → workflow-build-feature

Why Run Agents in Parallel? [HIGH freedom]

• Compare approaches: Same prompt across 3 models → pick the best result
• Isolate work: Each agent edits its own files without conflicts
• Delegate background tasks: Offload bug fixes, tests, docs while you work on something else
• Speed: Multiple independent tasks done simultaneously

Git Worktrees (Local Parallel Agents) [LOW freedom — run exactly]

How It Works

Cursor creates isolated git worktrees for each agent. Each has its own:

• File system (changes don't affect other agents)
• Build/test environment
• Branch

When an agent finishes, click Apply to merge changes back.

Starting a Worktree Agent

1. Open the agent dropdown
2. Select the worktree option
3. Submit your prompt
4. While it runs, start another agent in a different worktree

Best Use Cases

• Running the same hard problem across 3 models simultaneously
• Implementing 2 independent features at once
• Having one agent write tests while another writes implementation
• Trying 2 different architectural approaches before choosing

After Agents Finish

• Review diffs side-by-side
• Cursor suggests which solution it recommends (multi-agent judging)
• Click Apply on the winner
• Discard the others

Cloud Agents (Background Delegation) [HIGH freedom]

When to Use

Delegate tasks you'd otherwise put on a todo list:

• Bug fixes that came up while working on something else
• Writing tests for existing code
• Documentation updates
• Refactoring recent changes
• Dependency updates

Starting a Cloud Agent

• From Cursor editor: agent dropdown → cloud option
• From web: cursor.com/agents
• From phone: Cursor mobile app
• From Slack: @Cursor <task description>

How Cloud Agents Work

1. Describe the task + relevant context
2. Agent clones your repo, creates a branch
3. Works autonomously (you can close your laptop)
4. Opens a PR when finished
5. You get notified (Slack, email, or web)
6. Review and merge

Writing Good Delegation Prompts

# Good delegation prompt
Fix the bug where users see a 500 error when they submit the onboarding form
with a duplicate email. The error should show an inline message "Email already
in use" instead of crashing. See `app/onboarding/actions.ts` for the server
action and `app/onboarding/page.tsx` for the form.

# Bad delegation prompt
Fix the email bug

Include:

• Exact behaviour (current vs expected)
• File paths if known
• Acceptance criteria
• Any constraints ("don't change the API contract")

Running Multiple Models on the Same Prompt [LOW freedom — run exactly]

1. Open agent dropdown
2. Select multiple models
3. Submit prompt once
4. Cursor runs all models in parallel
5. Compare results; Cursor recommends the best

Best for:

• Architecturally significant decisions
• Hard bugs where different models take different approaches
• When you want to verify the solution is correct

Notifications [LOW freedom — run exactly]

When running many agents, configure:

• Settings → notifications → agent completion
• Sounds for agent completion (hear it finish across the room)
• Slack integration for cloud agents

Patterns [HIGH freedom]

The Parallel Spike

Run 2-3 agents with different approaches to a hard problem:

• Agent A: "Use optimistic updates with TanStack Query"
• Agent B: "Use server-sent events for real-time sync"
• Agent C: "Use Supabase Realtime subscriptions" Compare all three, pick the cleanest.

The Background Test Writer

While implementing feature X locally:

• Cloud agent: "Write tests for the auth flow in features/auth/"
• You: implement feature X
• Merge both when done

The Parallel Review

One agent reviews for security, another for performance:

• Agent A: "Review app/api/ for security issues (auth, input validation, RLS)"
• Agent B: "Review app/api/ for performance (N+1s, missing indexes, large payloads)"

Worktree Tips [LOW freedom — run exactly]

• Each worktree needs its own node_modules if deps differ
• Share .env by symlinking or copying to each worktree
• Worktrees share git history — easy to cherry-pick between them
• Clean up finished worktrees: git worktree remove <path>