Parallel Subagents — Your AI Agent Can Now Delegate

The Bottleneck

You ask your AI agent to review a project. It reads files one by one — task-service.ts, then storage.ts, then each command handler. You wait. Two minutes pass. You can't ask anything else until it's done.

Single-agent architectures hit a wall when tasks get complex. Reviewing a codebase, exploring an unfamiliar project, planning a refactor — these tasks take minutes, and during that time, you're blocked.

Delegate, Don't Wait

Aii CLI v0.15.0 introduces parallel subagents — specialized AI agents that the lead agent can spawn to handle delegated tasks. Each subagent runs its own ReAct loop with tools, in its own context window, and returns a compressed summary when done.

Let's see it in action with TaskPilot — a file-based CLI task board (think Trello from the terminal). It's a small TypeScript project with 15 source files across commands, services, models, and storage layers.

text

> Review this project in the background while I add a new "archive" command

● Your background code review has been launched.
  The review subagent is now analyzing the TaskPilot codebase.

  ● Running 1 agent...
    └─ Review (Code review of TaskPilot...) · 36 tool uses
       └ Running (2m 15s)

> Now let's add the archive command. Read src/commands/done.ts as a reference.

● Sure! Let me read the done command to understand the pattern...

The lead agent continues helping you build the archive command. The review agent reads all 15 source files, runs through 36 tool calls, and works in parallel. When it finishes, the results appear as a notification.

Five Capabilities

1. Background Execution

Spawn agents that work while you keep chatting. Here we explore TaskPilot's data layer while continuing to work:

text

> Use the explore agent in the background to map how tasks flow from
  CLI commands through the service layer to file storage

● Running 1 agent...
  └─ Explore (Map task data flow...) · 18 tool uses
     └ Running (45s)

> While that runs — what's the cleanest way to add filtering by date?

● Looking at your current filter logic in task-service.ts...

The parent agent returns immediately. Use TaskOutput to retrieve results when ready.

2. Parallel Agents

Launch multiple agents simultaneously for independent tasks. TaskPilot has 6 CLI commands and 4 test suites — perfect for splitting the work:

text

> Explore the command layer and review the test coverage — in parallel

● Running 2 agents...
  ├─ Explore (Command layer: add, list, move...) · 12 tool uses
  │  └ Running (30s)
  └─ Review (Test coverage across 4 suites...) · 21 tool uses
     └ Running (1m 10s)

Each agent has its own context window and tool access. The explore agent reads src/commands/, while the review agent independently analyzes tests/. No interference.

3. Agent Continuation

Pick up where a previous agent left off. After the review agent finishes analyzing TaskPilot:

text

> Continue that review agent — what did you find about error handling
  in the storage layer?

● Continuing agent_abc123 with full context preserved...

  Based on my earlier review of storage.ts, there are two concerns:
  1. No retry logic if the JSON file is locked by another process
  2. The directory creation in ensureDir() doesn't handle permission errors

The continued agent retains its entire message history and everything it discovered. No need to re-explain the codebase.

4. Worktree Isolation

Run agents in isolated git worktrees for safe experimentation:

text

> In an isolated worktree, refactor task-service.ts to separate
  the filtering logic into its own module

● Worktree created: task-agent_xyz (branch: task-agent_xyz)
  Agent operating on isolated copy...

  Created src/services/filter-service.ts
  Modified src/services/task-service.ts
  Updated tests/services/task-service.test.ts

  Worktree preserved at: .worktrees/task-agent_xyz
  Branch: task-agent_xyz (3 commits ahead)

The agent works on a complete copy of your repo. If it makes changes, the worktree and branch are preserved for your review. If no changes, it's automatically cleaned up.

5. Built-in Specialists

Three built-in agent types with specialized system prompts and tool configurations:

Explore — Fast codebase exploration. "How does TaskPilot persist data?", "Find all validation logic"
Review — Code quality analysis. Bug finding, security audit, TypeScript strict compliance
Plan — Architecture planning. "How should I add board switching?", "Plan a plugin system"

Plus custom agents via .aii/agents/ for your own workflows.

How It Works

The architecture is lightweight and in-process:

text

Parent Agent (your session)
  "Review TaskPilot and explore the CLI"

       |                    |
       v                    v

  Task("review")       Task("explore")

       |                    |
       v                    v

  +----------------+   +----------------+
  | Review Agent   |   | Explore Agent  |
  | 36 tool uses   |   | 12 tool uses   |
  | Own context    |   | Own context    |
  +-------+--------+   +-------+--------+
          |                     |
          v                     v

  Compressed results ---> parent context

Each subagent gets:

Fresh context window — no parent history pollution
Filtered tools — no recursive Task spawning
Compressed results — only the essential findings return to the parent
Automatic cleanup — sessions expire after 10 minutes, worktrees auto-remove

Model Flexibility

Subagents can use any model your Aii Server supports. The lead agent can override the model per task:

text

Task(subagent: "review", prompt: "...", model: "claude-sonnet-4-6")

Use a cheaper model for exploration and a stronger model for code review — all in the same session.

A Real Session

Here's what a full parallel session looks like with TaskPilot:

text

> I just cloned aii-taskpilot. Give me a full picture — explore the
  architecture, review the code quality, and plan what I should
  build next. Do it all in parallel.

● Launching 3 subagents...

  ● Running 3 agents...
    ├─ Explore (Architecture analysis...) · 15 tool uses
    │  └ Running (35s)
    ├─ Review (Code quality audit...) · 28 tool uses
    │  └ Running (1m 45s)
    └─ Plan (Feature roadmap...) · 11 tool uses
       └ Running (40s)

  ✓ Explore: Complete (35s)
  ✓ Plan: Complete (40s)
  ...still waiting on Review...
  ✓ Review: Complete (1m 45s)

● Here's your full picture:

  **Architecture**: Clean 4-layer design (commands → service → models
  → storage). Each CLI command is independent. Data stored as JSON
  in ~/.taskpilot/default.json.

  **Code Quality**: 8/10. Strong TypeScript strict compliance. Two
  issues found: no file locking in storage.ts, and the stats command
  doesn't handle empty boards gracefully.

  **Recommended Next Features**:
  1. Board switching (multiple named boards)
  2. Task archiving (soft delete)
  3. Due dates with color-coded urgency

Three agents. Three minutes of work. One coherent summary. You didn't wait for any of it.

Try It

bash

npm install -g @aiiware/aii@latest

Then in any project:

text

> Use the review agent to audit this codebase

Your agent will delegate to a specialist. You keep working.

Parallel subagents ship in Aii CLI v0.15.0. Requires Aii Server v0.5.10+ and a model that supports tool calling (Claude, OpenAI, DeepSeek, Gemini).