DocsAgent Workflows
View as Markdown

Multi-Agent Programming

Running multiple AI agents in parallel for maximum productivity

Overview#

Multi-agent programming is the practice of running multiple AI coding agents simultaneously, each working on different tasks in isolated environments. Agentastic makes this possible through git worktrees and containers.

Why Multiple Agents?#

Traditional AI Coding#

code
You → Agent → Wait → Review → You → Agent → Wait → Review...

You're blocked while the agent works. One task at a time.

Multi-Agent Coding#

code
You → Agent 1 (auth feature) ↘ You → Agent 2 (API endpoints) → All working in parallel You → Agent 3 (test coverage) ↗

Multiple tasks progress simultaneously. Review when ready.

Setting Up Multi-Agent Workflows#

Step 1: Plan Your Tasks#

Break your work into independent pieces:

TaskAgentBranch
User authenticationClaudefeature-auth
API endpointsCodexfeature-api
Database schemaClaudefeature-db
Unit testsAiderfeature-tests

Step 2: Launch Agents from Agent Home#

  1. Open Agent Home
  2. Write your first task prompt
  3. Select agents and instance counts
  4. Click Send

Repeat for each task, or use multi-instance launching:

  • Select multiple agents in the picker
  • Set instance counts (e.g., Claude ×2, Codex ×1)
  • Each instance gets its own worktree

Step 3: Monitor Progress#

Track agents in the Agents navigator tab:

  • See all active worktrees
  • Check terminal output
  • Switch between agents with Cmd+Option+Down/Up

Step 4: Review and Merge#

As agents complete:

  1. Switch to the agent's worktree
  2. Review changes in Diff Viewer
  3. Run Code Review for AI feedback
  4. Create PR or merge directly

Parallel Agent Strategies#

Strategy 1: Feature Decomposition#

Split a feature into independent parts:

code
Feature: User Dashboard Agent 1: Backend API - Create dashboard endpoints - Add data aggregation Agent 2: Frontend Components - Build dashboard UI - Add charts and widgets Agent 3: Tests - Write API tests - Write component tests

Strategy 2: Same Task, Different Approaches#

Get multiple perspectives on the same problem:

code
Task: Implement caching Agent 1 (Claude): "Implement Redis-based caching" Agent 2 (Codex): "Implement in-memory caching" → Compare approaches, pick the best

Strategy 3: Iterative Refinement#

Chain agent outputs:

code
1. Agent 1: Generate initial implementation 2. Review, provide feedback 3. Agent 2: Refactor based on feedback 4. Agent 3: Add tests and documentation

Strategy 4: Code Review Pipeline#

Use agents to review each other:

code
1. Agent 1: Implement feature 2. Agent 2: Review Agent 1's code 3. Agent 3: Write tests for the feature 4. You: Final review and merge

Best Practices#

Keep Tasks Independent#

Good task split:

  • Auth system (independent)
  • Payment processing (independent)
  • Email notifications (independent)

Bad task split:

  • Create user model (dependency)
  • Add user validation (depends on model)
  • Build user API (depends on both)

Use Clear Branch Names#

code
feature-auth-backend feature-auth-frontend feature-payments-api bugfix-login-timeout

Set Up Proper Context#

For each agent:

  • Use @ mentions for relevant files
  • Attach screenshots if UI-related
  • Reference existing patterns

Start Small#

Begin with 2-3 agents:

  1. Learn the workflow
  2. Understand review overhead
  3. Scale up gradually

Monitor Resource Usage#

Multiple agents = multiple processes:

  • Watch CPU and memory
  • Close completed agents promptly
  • Use containers for resource limits

Example Workflow#

Scenario: Building a Blog Feature#

Tasks identified:

  1. Database models for posts and comments
  2. REST API endpoints
  3. Admin UI for managing posts
  4. Public blog page
  5. Tests

Agent assignments:

bash
# Terminal 1: Launch database agent # In Agent Home: # Prompt: "Create database models for a blog with posts and comments..." # Branch: blog-db # Agent: Claude # Terminal 2: Launch API agent (after db is done) # Prompt: "Create REST API endpoints for blog posts..." # Branch: blog-api # Agent: Codex # Terminal 3: Launch UI agent # Prompt: "Build admin UI for managing blog posts..." # Branch: blog-admin-ui # Agent: Claude # Terminal 4: Launch public page agent # Prompt: "Create public blog page with post listing..." # Branch: blog-public # Agent: Claude

Review order:

  1. Review and merge blog-db first (foundation)
  2. Rebase blog-api onto main, review and merge
  3. Review blog-admin-ui and blog-public in parallel
  4. Create test agent after features are stable

Handling Conflicts#

Prevention#

  • Assign non-overlapping files to each agent
  • Use clear boundaries (backend vs frontend)
  • Communicate shared interfaces upfront

Resolution#

If agents touch the same files:

  1. Merge the first agent's work
  2. Rebase the second agent's branch:
    bash
    git checkout blog-api git rebase main # Resolve conflicts
  3. Or use interactive rebase to cherry-pick changes

Using Diff Viewer#

Compare agent branches:

  1. Open Diff Viewer
  2. Compare agent-1-branch vs agent-2-branch
  3. Identify conflicts before merging

Resource Management#

CPU and Memory#

Each agent uses resources:

  • Claude Code: ~200-500MB RAM
  • Node.js projects: +500MB for node_modules
  • Containers: Additional overhead

Disk Space#

Worktrees share git objects but duplicate working files:

  • 1GB project × 5 worktrees ≈ 5GB disk space
  • Clean up completed worktrees promptly

Network#

API calls from multiple agents:

  • Rate limits may apply
  • Costs accumulate faster
  • Monitor API usage

Troubleshooting#

Agent Running Slow#

  • Too many agents competing for resources
  • Close unused agents
  • Use containers with CPU limits

Merge Conflicts#

  • Agents worked on overlapping code
  • Review changes carefully
  • Consider sequential approach for coupled tasks

Context Lost Between Agents#

  • Each agent has isolated context
  • Re-share relevant context when needed
  • Use consistent naming and patterns

Tips for Success#

  1. Plan before launching - Map out tasks and dependencies
  2. Start independent - Launch tasks that don't depend on each other
  3. Review promptly - Don't let agent work pile up
  4. Clean up regularly - Remove completed worktrees
  5. Learn from results - Note which task splits work best

Other Multi-Agent Runners#

Agentastic isn't the only tool tackling parallel agent workflows. See how it compares: