Parallel Agents

How It Works

When the agent encounters a task that can be decomposed into independent subtasks, it uses the task tool to spawn one or more subagents. Each subagent runs as an independent agent instance with its own message history, tool calls, and results. The parent agent collects all results and synthesizes them into a coherent response.

Parent Agent
  ├── Task 1: Search for deprecated API usage (subagent)
  ├── Task 2: Analyze test coverage gaps (subagent)
  └── Task 3: Check for type errors in affected files (subagent)

  → All three run simultaneously
  → Parent collects results and summarizes findings

The parent agent decides when to use parallel execution based on the nature of the request. Tasks that are independent (no shared state, no ordering dependency) are good candidates for parallelization. Tasks that depend on each other's results are executed sequentially.

Subagent Execution

Each subagent is a full agent instance with access to the complete tool set. It receives a focused prompt from the parent agent and works independently until it finishes.

Subagent Lifecycle

• The parent agent creates a task with a description and detailed prompt.
• A new agent instance is spawned with its own context window.
• The subagent receives the project instructions (CREOR.md, rules) plus its task-specific prompt.
• It executes tool calls, reads files, and performs work independently.
• When finished, it returns its result to the parent agent.
• The parent agent reads all subagent results and continues its workflow.

What Subagents Can Do

Git Worktree Isolation

When subagents need to modify files, they can be isolated using git worktrees. Each subagent works in its own worktree (a separate checkout of the repository) on its own branch, so their changes cannot conflict with each other or with the main working directory.

How Worktree Isolation Works

• The parent agent creates a new git worktree for each subagent that will modify files.
• Each worktree is a separate directory with its own checkout of the repository.
• The subagent works in its worktree, making changes on an isolated branch.
• When the subagent finishes, its changes can be merged back into the main branch.
• The worktree is cleaned up after the task is complete.

Main branch (your working directory)
  ├── worktree/task-1 (branch: task/migrate-user-dto)
  │   └── Subagent 1 edits files here
  ├── worktree/task-2 (branch: task/update-tests)
  │   └── Subagent 2 edits files here
  └── worktree/task-3 (branch: task/fix-type-errors)
      └── Subagent 3 edits files here

Merging Results

After all subagents complete, the parent agent can merge their branches back into the main branch. If there are conflicts, the parent agent handles them the same way it would handle any git merge conflict -- by reading the conflicting files and resolving them.

Batch Operations

The batch tool is a lighter-weight form of parallelism that combines multiple independent tool calls into a single operation. Unlike subagents, batch operations share the same agent context and do not create separate worktrees.

Batch vs. Subagents

The agent automatically decides between batch operations and subagents based on the complexity of the work. Simple, homogeneous operations (e.g., reading several files) use batch. Complex, multi-step workflows use subagents.

Use Cases

Multi-File Refactoring

When a refactoring touches many files, the parent agent can split the work into subagents that each handle a subset of files. This is especially useful for large-scale renames, import path changes, or API migrations.

Rename the UserService to AccountService across the entire
codebase. This affects approximately 40 files.

Parallel Research

When the agent needs to gather information from multiple sources, it can spawn subagents to search different parts of the codebase or web simultaneously.

Analyze the performance of our API endpoints. Check the
route handlers, database queries, middleware, and caching
layer for bottlenecks.

Independent Feature Work

For features that have independent components (e.g., frontend and backend, or multiple microservices), subagents can work on each component simultaneously.

Test Suite Updates

After a significant change, the agent can spawn subagents to update different test files in parallel, each in its own worktree to avoid conflicts.

Limitations

• Subagents cannot spawn their own subagents. Parallelism is limited to one level of nesting.
• Each subagent has its own context window, so very large tasks may still exceed context limits.
• Subagents cannot communicate with each other during execution. All coordination goes through the parent agent.
• Worktree creation and cleanup adds overhead. For very small tasks, sequential execution may be faster.
• Merge conflicts between subagent branches require manual resolution by the parent agent.
• The total number of concurrent subagents may be limited by system resources.