Skip to content

Agent Team

One agent is good. Multiple agents working together can be great — but only when the task actually calls for it.

Agent Team lets you split a task across multiple coding agents working in parallel. Each agent handles part of the work, and you can monitor their progress in real time.

The One Command To Remember

# Start 3 agents on a task
aios team 3:codex "Build the settings page, add tests, and update docs"

# Watch them work
aios team status --provider codex --watch

When To Use Teams (And When Not To)

Good fit for Agent Team

  • The task has independent parts (frontend + backend + tests + docs)
  • You already know the acceptance criteria ("tests must pass", "docs must be updated")
  • The work can be split without agents editing the same files
  • You're OK spending extra tokens for faster parallel execution

Bad fit for Agent Team

  • The requirement is still unclear — you're still figuring out what to build
  • It's a small bug or single-file fix
  • Multiple agents would step on each other's toes (editing the same files)
  • You're debugging something that needs stable, reproducible steps

When in doubt, use one agent

codex  # Start with a single agent
If the task turns out to be parallelizable, you can always start a team later.

Quick Checklist

Before starting a team, confirm all three:

  • [ ] The task splits into 2+ independent modules
  • [ ] Workers will NOT edit the same files
  • [ ] You can describe the acceptance criteria in one sentence

The 10-Minute Flow

1. Write A Clear Task

A good task description has three parts: goal, boundary, and acceptance criteria.

aios team 3:codex \
  "Improve login form error messages; \
   do not change the auth API; \
   run related tests and update docs before finishing"

2. Start Monitoring

aios team status --provider codex --watch

For a lighter view:

aios team status --provider codex --watch --preset minimal --fast

3. Check History And Failures

# Recent team runs
aios team history --provider codex --limit 20

# Only failed runs
aios team history --provider codex --quality-failed-only

4. Run A Quality Check Before Finishing

aios quality-gate pre-pr --profile strict

If the quality gate fails, inspect the failure first. Don't just start more workers.

How Many Agents Should I Use?

Count Command Best for
2 aios team 2:codex "task" First time, or when files might overlap
3 aios team 3:codex "task" Most daily features (recommended)
4 aios team 4:codex "task" Very independent modules with clear tests

If you see conflicts or duplicate edits, reduce the count — don't increase it.

Choosing A Provider

aios team 3:codex "task"       # Good for daily implementation
aios team 2:claude "task"      # Good for analysis or planning
aios team 2:gemini "task" --dry-run  # Preview without running

If Something Goes Wrong

A run was interrupted

Check what happened first:

aios team history --provider codex --limit 5

Then retry only the blocked parts:

aios team --resume <session-id> --retry-blocked --provider codex --workers 2

Don't just start a bigger team

Figure out why the previous run failed before starting a new one. More agents on a broken task won't help.

How Team Works Under The Hood

When you start a team, Harness CLI uses a GroupChat Runtime — a round-based system where agents share a conversation thread:

Round 1 → Planner analyzes the task and creates work items
Round 2 → N implementers work in parallel (one per work item)
Round 3 → Reviewer checks the results

If an agent gets stuck, the planner automatically re-plans the next round.

Blueprints

Blueprint Rounds Best for
bugfix plan → implement → review Simple fixes, small scope
feature plan → implement → review + security New features with quality checks
refactor plan → implement → review Pure refactoring, no new features
security assess → plan → implement → review Security-sensitive changes

Use the smallest blueprint that fits your task.

Blueprints, role cards, runtime manifests, executor manifests, and handoff schemas are packaged under scripts/lib/specs/. Team run state and evidence are still written to .aios/context-db/; .aios/memo/ is only for project memo records and is not the team runtime store.

Configuration

# Required for live execution
export AIOS_EXECUTE_LIVE=1
export AIOS_SUBAGENT_CLIENT=codex-cli  # or claude-code, gemini-cli

# How many agents run at once per round (default: 3)
export AIOS_SUBAGENT_CONCURRENCY=3

# Timeout per agent turn in ms (default: 10 min)
export AIOS_SUBAGENT_TIMEOUT_MS=600000

Team vs. Harness vs. Orchestrate

Need Use
Multiple agents on one task aios team ...
One agent working overnight aios harness run ...
Staged execution with gates aios orchestrate ...

New users should start with team. Orchestration is for advanced users who need strict staged execution.

Command Reference

# Start a team (dry-run by default)
aios team 3:codex "Ship feature X"

# Start a team with live execution
AIOS_EXECUTE_LIVE=1 AIOS_SUBAGENT_CLIENT=codex-cli \
  aios team 3:codex "Ship feature X"

# Watch current status
aios team status --provider codex --watch

# Recent history
aios team history --provider codex --limit 20

# Failures only
aios team history --provider codex --quality-failed-only

# Retry blocked jobs
aios team --resume <session-id> --retry-blocked --provider codex --workers 2

# Current session HUD
aios hud --provider codex

Advanced Operations Reference

The following commands are recommended for advanced users who are familiar with the basic flow.

HUD Presets

Preset Use case
minimal Long-running watches
compact Terminal-friendly summary
focused Balanced default
full Full diagnostics 
aios hud --provider codex
aios hud --watch --preset focused
aios hud --session <session-id> --json

Skill Candidates

Skill candidates are improvement suggestions extracted from failed sessions. Review them during failure retrospectives — not as a first step.

aios team status --show-skill-candidates
aios team skill-candidates list --session <session-id>
aios team skill-candidates export --session <session-id> --output ./candidate.patch.md

Human review required

Always review skill candidate patches before applying them, especially suggestions that modify skills, hooks, or MCP configuration.

Where To Go Next