Agents

Agents

Multi-agent orchestration (v0.4+) lives under app/src/main/agents/.

When it runs

Settings enable agents and the turn is classified as complex enough and the turn is not forced into project-coding single-agent mode.

Pipeline

flowchart LR
  In[Chat turn] --> Class[classify]
  Class -->|simple| Single[Single-agent ipc loop]
  Class -->|complex| Plan[plan]
  Plan --> Work[workers parallel]
  Work --> Syn[synthesize]
  Syn --> Out[Final answer + trail]

Loading

Key modules

File	Role
plan.ts / parse helpers	Produce worker steps
classify.ts	Complexity / routing
orchestrator / related	Drive the run
workers.ts	Per-step model+tools (MAX_TOOL_ROUNDS = 3)
Load / clamp / mutex	Concurrency and RAM safety
Scheduler	Timing / metering hooks

Workers reuse the same tools/skills execution path as single-agent chat.

Load protection

load-guard/ watches memory pressure. When past the configured kill threshold, the turn soft-stops instead of wedging the machine. Toggle/cutoff live in settings (llmeter-settings.json).

UI

• Collapsed agent trail in chat activity
• Settings → Agents panel for enablement and limits

Design docs

See:

• docs/superpowers/specs/2026-08-07-multi-agent-core-design.md
• docs/superpowers/plans/2026-08-07-multi-agent-core.md
• docs/superpowers/specs/2026-08-08-load-protection-design.md

Contributor nuances

1. Do not casually fall back to single-agent after tools already executed in a failed multi-agent synthesize — side effects may have landed. Follow comments in ipc.ts.
2. Worker tool-round budget is intentionally lower than the single-agent 15.
3. Keep metering/token accounting consistent with governance usage recording.
4. Tests: agents/*.test.ts (plan parse, assign, mutex, workers rounds, etc.).