Running Multiple AI Agents in Parallel

advanced 15 min 📋 Copy-paste ready

Sources not yet verified

parallelgit-worktreesmulti-agentworkflowpower-user

Scenario

Context: You have a complex feature with multiple independent parts that could be developed simultaneously

Goal: Learn to run multiple AI agents in parallel using git worktrees, dramatically accelerating multi-part tasks

Anti-pattern: Sequential execution of independent tasks, waiting for one agent to finish before starting another

Tools: Claude CodeGitHub CopilotCursorGit

Conversation

The Parallel Execution Pattern

AI agents are typically used one at a time, but independent tasks can run simultaneously. Using git worktrees, you can run multiple agents in isolated directories, each with its own context.

Why This Works:

• Git worktrees create separate working directories from one repo
• Each agent gets a clean, isolated workspace
• No context pollution between tasks
• Merge results via standard git operations

Tool Support:

• Claude Code / Copilot CLI: Multiple terminal sessions
• Cursor 2.0: Built-in multi-agent (up to 8 parallel)
• Pattern is tool-agnostic: Works with any AI coding assistant

Example: Building a Feature with Three Independent Parts

You're adding a new notification system with:

1. Backend API endpoints
2. Frontend React components
3. Database migrations and models

These can be developed in parallel.

👤 You

Set up parallel workspaces

git worktree add ../notifications-api feature/notifications-api
git worktree add ../notifications-ui feature/notifications-ui
git worktree add ../notifications-db feature/notifications-db

Create three isolated worktrees, each on its own feature branch. Each will have its own AI agent.

Now open three terminals (or use a terminal multiplexer like tmux) and start an agent in each worktree:

👤 You

Terminal 1: API Agent

cd ../notifications-api
claude # or 'gh copilot' or open in Cursor

Terminal 2: UI Agent

cd ../notifications-ui
claude

Terminal 3: Database Agent

cd ../notifications-db
claude

Each agent operates in isolation with clean context. No risk of one agent's context polluting another's work.

---

Terminal 1: API Agent

Give focused instructions for just the API work:

👤 You

Build the notification API endpoints:

1. POST /api/notifications - Create notification
2. GET /api/notifications - List user notifications
3. PATCH /api/notifications/:id/read - Mark as read
4. DELETE /api/notifications/:id - Dismiss notification

Use existing auth middleware. Add request validation with Zod. Include rate limiting.

🤖 AI

I'll create the notification API endpoints. Let me first check the existing patterns in your codebase...

[Examines existing route files, middleware, validation patterns]

Creating:

• src/routes/notifications.ts - Route handlers
• src/validators/notifications.ts - Zod schemas
• tests/routes/notifications.test.ts - API tests

// src/routes/notifications.ts
import { Router } from 'express';
import { authMiddleware } from '../middleware/auth';
import { rateLimiter } from '../middleware/rate-limit';
import { createNotificationSchema, ... } from '../validators/notifications';

export const notificationsRouter = Router();

notificationsRouter.use(authMiddleware);
notificationsRouter.use(rateLimiter({ windowMs: 60000, max: 100 }));

notificationsRouter.post('/', async (req, res) => { ... });
// ...

API layer complete. Running tests... 12/12 passing.

This agent focuses only on API work, producing clean, focused changes.

---

Terminal 2: UI Agent (Running Simultaneously)

The UI agent works independently:

👤 You

Build the notification UI components:

1. NotificationBell - Icon with unread count badge
2. NotificationPanel - Dropdown showing recent notifications
3. NotificationItem - Single notification with read/dismiss actions
4. useNotifications hook - Fetch and manage notification state

Use existing design system (Tailwind + Radix UI). Match the style of UserMenu component.

🤖 AI

I'll build the notification UI. Let me examine your design system patterns first...

[Examines UserMenu, existing components, Tailwind config]

Creating:

• src/components/notifications/NotificationBell.tsx
• src/components/notifications/NotificationPanel.tsx
• src/components/notifications/NotificationItem.tsx
• src/hooks/useNotifications.ts
• src/components/notifications/index.ts - Barrel export

// NotificationBell.tsx
export function NotificationBell() {
  const { unreadCount, isLoading } = useNotifications();
  
  return (
    <Popover>
      <PopoverTrigger className="relative">
        <BellIcon className="h-5 w-5" />
        {unreadCount > 0 && (
          <Badge variant="destructive" className="absolute -top-1 -right-1">
            {unreadCount}
          </Badge>
        )}
      </PopoverTrigger>
      <PopoverContent>
        <NotificationPanel />
      </PopoverContent>
    </Popover>
  );
}

UI components complete. Storybook stories added.

The UI agent produces focused UI changes while the API agent works simultaneously.

---

Terminal 3: Database Agent (Also Running Simultaneously)

The database agent handles schema and models:

👤 You

Create the database layer for notifications:

1. Migration for notifications table
2. Prisma/Drizzle model definition
3. Repository pattern for data access
4. Indexes for performance (user_id, created_at, is_read)

Follow existing migration and repository patterns in the codebase.

🤖 AI

I'll create the database layer. Examining existing patterns...

[Examines existing migrations, Prisma schema, repository files]

Creating:

• prisma/migrations/20240115_notifications.sql
• prisma/schema.prisma (updated with Notification model)
• src/repositories/notification.repository.ts

-- prisma/migrations/20240115_notifications.sql
CREATE TABLE notifications (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  type VARCHAR(50) NOT NULL,
  title VARCHAR(255) NOT NULL,
  body TEXT,
  is_read BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  read_at TIMESTAMPTZ
);

CREATE INDEX idx_notifications_user_unread ON notifications(user_id, is_read) WHERE is_read = FALSE;
CREATE INDEX idx_notifications_user_created ON notifications(user_id, created_at DESC);

Database layer complete. Migration tested against dev database.

Three agents working in parallel, each with focused context and no interference.

---

Merging Results

Once all agents complete, merge the branches:

👤 You

Return to main repo

cd /path/to/main-repo

Merge all feature branches

git checkout main
git merge feature/notifications-db -m "Add notifications database layer"
git merge feature/notifications-api -m "Add notifications API endpoints"
git merge feature/notifications-ui -m "Add notifications UI components"

Clean up worktrees

git worktree remove ../notifications-api
git worktree remove ../notifications-ui
git worktree remove ../notifications-db

Standard git merge brings all parallel work together. Resolve any conflicts as normal.

---

Pattern: Multi-Agent Review (Writer + Reviewer)

Beyond parallel development, use separate agents to review each other's work:

Agent 1 (Writer): Creates the implementation
Agent 2 (Reviewer): Reviews with fresh context, finds issues

Research shows that multi-agent debate with diverse models (Claude + Gemini + GPT) achieves 91% accuracy vs 82% for identical models.

👤 You

In writer worktree

cd ../feature-writer
claude

"Implement the caching layer for the search API"

After completion, in reviewer worktree

cd ../feature-reviewer
claude

"Review the caching implementation in src/services/cache.ts. Look for:

• Edge cases in cache invalidation
• Memory leak potential
• Race conditions in concurrent access
• Missing error handling"

Separation of concerns: the writer optimizes for implementation, the reviewer for quality.

---

Tool-Specific Notes

Claude Code / Copilot CLI

Multiple terminal sessions, each with claude or gh copilot.

Cursor 2.0

Built-in multi-agent support:

• Open Settings > Agent > Enable Multi-Agent
• Run up to 8 parallel agents with auto-evaluation
• Use /parallel command to spawn agent swarm

Windsurf Cascade

• Cascade "flows" can spawn sub-agents automatically
• Less manual setup, more automatic parallelization

GitHub Copilot Coding Agent

• Runs in GitHub Actions (background agent)
• Assign issues with @copilot mention
• Multiple issues = multiple parallel agents

Key Takeaways

• Use git worktrees to create isolated workspaces for parallel AI agents
• Independent tasks (API, UI, DB) can run simultaneously with separate agents
• Fresh context in each worktree prevents cross-contamination of agent work
• Merge parallel work via standard git operations
• Multi-agent review (writer + reviewer) catches issues a single agent misses

Try It Yourself

Prompt Template

# Create worktrees for parallel work
git worktree add ../feature-part-a feature/part-a
git worktree add ../feature-part-b feature/part-b

# Start agents in separate terminals
cd ../feature-part-a && claude
cd ../feature-part-b && claude

Copy template

Variations to Try

• TDD split: One agent writes failing tests, another implements to pass them
• Architect/Builder: One agent plans the design, others implement each component
• Writer/Reviewer: One agent implements, another reviews with fresh context

Related Content

📖 Agentic Loops 📖 Agentic Workflows

Sources

✓ Simon Willison: Parallel Execution ⓘ

×

Embracing the Parallel Coding Agent Lifestyle

Power user pattern for running multiple AI agents in parallel. Key insight: review is the bottleneck, not generation. Four categories of parallelizable work identified: research, documentation, maintenance, spec-driven. Scout pattern (Snyder) used to discover complexity before committing.

Key Findings:

• Four use cases for parallel agents: research/PoCs, system understanding, low-stakes maintenance, and spec-driven work
• Fresh checkouts to /tmp preferred over git worktrees for isolation
• The 'scout pattern' (via Snyder): run throwaway attempts to discover complexity

Credibility: high

Referenced by:

Running Multiple AI Agents in Parallel

View Source ↗

✓ Anthropic: Multi-Agent Patterns ⓘ

×

Multi-Agent Collaboration Best Practices

Anthropic

Official guidance on multi-agent patterns including debate (multiple models reviewing each other), TDD splits (one writes tests, another implements), and Architect/Implementer separation. Research shows diverse model debate (Claude + Gemini + GPT) achieves 91% on GSM-8K vs 82% for identical models.

Key Findings:

• Separate Claude instances can communicate via shared scratchpads
• Multi-agent debate with diverse models outperforms single-model approaches
• Writer/Reviewer and TDD splits improve output quality

Credibility: high

Referenced by:

Agentic Loops TDD for AI Agents Running Multiple AI Agents in Parallel

View Source ↗