Parallel Agent Execution

Run multiple agents simultaneously on the same task to explore different approaches, leverage diverse agent strengths, and keep the best results.

Overview

Agent Harbor supports three parallel execution patterns:

1. Multiple Agent Types: Launch different agents (Claude, Codex, etc.) in parallel
2. Multiple Instances: Launch multiple instances of the same agent
3. Combined: Mix both approaches for maximum exploration

Each agent works in an isolated filesystem branch, preventing conflicts and enabling easy comparison.

Multiple Agent Types

Different agents have unique strengths. Launch them in parallel to leverage their capabilities:

ah task create --agent claude --agent codex --prompt "Implement a caching layer"

This launches both Claude and Codex on the same task, each in their own isolated workspace.

Why Use Multiple Agents?

Multiple Instances

Launch multiple instances of the same agent to explore different approaches:

ah task create --agent claude --instances 3 --prompt "Find and fix all security vulnerabilities"

This launches 3 Claude instances, each potentially taking a different approach.

With Model Override

Specify different models for different quality/speed tradeoffs:

ah task create --agent claude --model sonnet --instances 2 --prompt "Optimize database queries"

Combined Approach

Mix agents and instances for comprehensive exploration:

ah task create \
  --agent claude --instances 2 \
  --agent codex \
  --prompt "Refactor the authentication module"

This launches:

• 2 Claude instances
• 1 Codex instance

All working in parallel on the same task.

Parameter Behavior

The --instances and --model flags apply to the most recently specified --agent:

# 2 Claude instances with Sonnet, 1 Codex instance
ah task create \
  --agent claude --model sonnet --instances 2 \
  --agent codex
 
# 1 Claude, 3 OpenHands instances
ah task create \
  --agent claude \
  --agent openhands --instances 3

Filesystem Isolation

Each agent instance gets its own isolated filesystem branch using Agent Harbor’s snapshot system:

Base Snapshot (task start)
├── Branch: task-claude-1
├── Branch: task-claude-2
└── Branch: task-codex-1

This provides:

• No Conflicts: Agents can’t interfere with each other
• Easy Comparison: Review each branch’s changes independently
• Selective Merging: Cherry-pick the best solution

Comparing Results

After parallel execution completes, compare the different approaches:

View Branches

git branch --list 'task-*'

Compare Changes

# View changes from first Claude instance
git diff main..task-claude-1
 
# View changes from Codex
git diff main..task-codex-1
 
# Compare two agent results
git diff task-claude-1..task-codex-1

Review Test Results

Each branch runs tests independently. Review the results:

# Check test results for each branch
ah task results <task-id>

Selecting the Best Result

After reviewing, you have several options:

Merge One Branch

If one agent produced the best solution:

git checkout main
git merge task-claude-1

Cherry-Pick Commits

Combine elements from multiple branches:

git checkout main
git cherry-pick <commit-from-claude-1>
git cherry-pick <commit-from-codex-1>

Create a Combined Solution

Use a new task to synthesize the best parts:

ah task create --agent claude --prompt "Review the solutions in branches task-claude-1 and task-codex-1. Create a combined solution taking the best elements from each."

Use Cases

Exploratory Tasks

When the best approach isn’t clear, let multiple agents explore:

ah task create \
  --agent claude --instances 3 \
  --prompt "Find the best way to optimize startup time"

Quality Assurance

Get multiple perspectives on critical changes:

ah task create \
  --agent claude --agent codex \
  --prompt "Review and improve the security of the payment processing module"

Competitive Benchmarking

Compare agent performance on your specific codebase:

ah task create \
  --agent claude --agent codex --agent openhands \
  --prompt "Implement feature X according to spec.md"

Configuration

Configure default parallel execution behavior:

# .agents/config.toml
 
[parallel]
# Default number of instances when --instances not specified
default_instances = 1
 
# Maximum concurrent agents per task
max_concurrent = 5
 
# Snapshot provider for branch isolation
snapshot_provider = "auto"  # zfs, btrfs, agentfs, git
 
[parallel.branch_naming]
# Template for branch names
template = "task-{agent}-{instance}"

Resource Considerations

Running multiple agents consumes more resources:

Consider:

• Available system resources
• API rate limits and costs
• Task complexity and expected runtime