Multi-Agent Programming

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

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

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

Multi-Agent Coding

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:

Task	Agent	Branch
User authentication	Claude	feature-auth
API endpoints	Codex	feature-api
Database schema	Claude	feature-db
Unit tests	Aider	feature-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:

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:

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:

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:

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

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:

# 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:

   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