> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run multiple AI agents in parallel

> Speed up development by running several AI coding agents simultaneously, each working on independent tasks in isolated git worktrees.

With traditional AI coding, you wait for one agent to finish before starting the next — your time is blocked while the agent works. Multi-agent programming breaks that bottleneck. You launch several agents at once, each tackling a separate task in its own isolated environment, and you review the results when they are ready. Agentastic makes this possible through git worktrees and containers, giving every agent a clean, conflict-free workspace.

## Why run multiple agents?

**Traditional serial workflow:**

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

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

**Multi-agent parallel workflow:**

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

Multiple tasks progress simultaneously. Review each one when it is ready.

## Setting up a multi-agent workflow

<Steps>
  <Step title="Plan your tasks">
    Break your work into independent pieces. Each agent needs a clearly scoped task that does not depend on another agent finishing first.

    | Task                | Agent  | Branch          |
    | ------------------- | ------ | --------------- |
    | User authentication | Claude | `feature-auth`  |
    | API endpoints       | Codex  | `feature-api`   |
    | Database schema     | Claude | `feature-db`    |
    | Unit tests          | Aider  | `feature-tests` |
  </Step>

  <Step title="Launch agents from Agent Home">
    1. Open **Agent Home**
    2. Write your first task prompt
    3. Select the agent and instance count
    4. Click **Send**

    Repeat for each task, or use multi-instance launching to spin up several agents at once:

    * Select multiple agents in the picker
    * Set instance counts (for example, Claude ×2, Codex ×1)
    * Each instance gets its own worktree automatically
  </Step>

  <Step title="Monitor progress">
    Track all running agents in the **Agents** navigator tab:

    * See all active worktrees and their status
    * Check terminal output for each agent
    * Switch between agents with `Cmd+Option+Down` / `Cmd+Option+Up`
  </Step>

  <Step title="Review and merge">
    As each agent completes its task:

    1. Switch to the agent's worktree
    2. Review changes in the Diff Viewer
    3. Run **Code Review** for AI feedback
    4. Create a PR or merge directly into your main branch
  </Step>
</Steps>

## Parallel agent strategies

<AccordionGroup>
  <Accordion title="Strategy 1: Feature decomposition">
    Split a large feature into independent parts and assign each to a different agent. This is the most common multi-agent pattern.

    ```
    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
    ```

    Each agent works on a distinct layer of the stack, so there is minimal risk of overlapping file changes.
  </Accordion>

  <Accordion title="Strategy 2: Same task, different approaches">
    Launch two agents with the same goal but different instructions to get competing implementations. Compare the results and pick the best one.

    ```
    Task: Implement caching

    Agent 1 (Claude): "Implement Redis-based caching"
    Agent 2 (Codex):  "Implement in-memory caching"

    → Compare approaches, pick the best
    ```

    This is useful when you are unsure which approach will suit your architecture.
  </Accordion>

  <Accordion title="Strategy 3: Iterative refinement">
    Chain agent outputs so that each agent builds on the previous one's work.

    ```
    1. Agent 1: Generate the initial implementation
    2. You review and provide feedback
    3. Agent 2: Refactor based on your feedback
    4. Agent 3: Add tests and documentation
    ```

    Unlike a purely parallel workflow, this strategy introduces intentional sequencing at the review steps — you control when each stage begins.
  </Accordion>

  <Accordion title="Strategy 4: Code review pipeline">
    Use agents to review each other's work before you do your final pass.

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

    This gives you a structured quality gate without having to review every line yourself first.
  </Accordion>
</AccordionGroup>

## Best practices

### Keep tasks independent

Good task splits avoid dependencies between agents:

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

Avoid splits where one agent's output is another's input at the start:

* Create user model *(other tasks depend on this)*
* Add user validation *(depends on the model)*
* Build user API *(depends on both)*

For dependent tasks, run them sequentially — launch the next agent only after merging the previous one's output.

### Use clear branch names

Descriptive branch names make it easier to track what each agent is working on:

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

### Give each agent proper context

* Use `@` mentions to reference relevant files in your prompt
* Attach screenshots for UI-related tasks
* Reference existing patterns you want the agent to follow

### Start small

Begin with two or three agents:

1. Learn the review overhead
2. Get comfortable with the worktree workflow
3. Scale up once the process feels natural

### Monitor resource usage

Each agent runs as a separate process with its own resource footprint. Watch CPU and memory, close completed agents promptly, and use containers if you need hard resource limits.

## Example workflow: 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:**

| Agent  | Task               | Branch          |
| ------ | ------------------ | --------------- |
| Claude | Database models    | `blog-db`       |
| Codex  | REST API endpoints | `blog-api`      |
| Claude | Admin UI           | `blog-admin-ui` |
| Claude | Public blog page   | `blog-public`   |

**Review order:**

1. Review and merge `blog-db` first — it is the foundation
2. Rebase `blog-api` onto main, then review and merge
3. Review `blog-admin-ui` and `blog-public` in parallel
4. Create a test agent after the features are stable

## Handling conflicts

### Prevention

The best way to avoid conflicts is to assign non-overlapping files to each agent before you launch. Define clear boundaries — for example, backend vs. frontend — and communicate shared interface contracts upfront so each agent knows what to expect from the other.

### Resolution

If two agents end up touching the same files:

1. Merge the first agent's work into main
2. Rebase the second agent's branch:

```bash theme={null}
git checkout blog-api
git rebase main
# Resolve conflicts
```

3. Alternatively, use an interactive rebase to cherry-pick only the changes you want.

### Using Diff Viewer

Before merging, compare agent branches directly to spot conflicts early:

1. Open the **Diff Viewer**
2. Compare `agent-1-branch` vs `agent-2-branch`
3. Identify and resolve conflicts before either branch lands on main

## Resource management

Understanding the resource cost of each agent helps you decide how many to run at once.

| Resource                          | Estimate                 |
| --------------------------------- | ------------------------ |
| Claude Code RAM                   | \~200–500 MB per agent   |
| Node.js project (node\_modules)   | +500 MB per worktree     |
| Container overhead                | Additional per container |
| Disk (1 GB project × 5 worktrees) | \~5 GB working files     |

<Note>
  Worktrees share git objects but duplicate working files. Clean up completed worktrees promptly to reclaim disk space.
</Note>

Running multiple agents also multiplies API calls. Rate limits may apply, and costs accumulate faster than with a single agent — keep an eye on your API usage.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent is running slowly">
    Too many agents competing for CPU or memory can slow each one down. Try:

    * Closing completed or idle agents
    * Reducing the number of agents running concurrently
    * Using containers with CPU limits to prevent any single agent from monopolizing resources
  </Accordion>

  <Accordion title="Merge conflicts">
    Agents worked on overlapping files. To recover:

    * Review both sets of changes carefully before resolving
    * For tightly coupled tasks, consider a sequential approach next time rather than running them in parallel
  </Accordion>

  <Accordion title="Context lost between agents">
    Each agent has isolated context — it does not know what other agents are working on. To keep things coherent:

    * Re-share relevant context when starting a downstream agent
    * Use consistent naming conventions and patterns across all agent prompts
    * Document shared interfaces explicitly in your prompts
  </Accordion>
</AccordionGroup>