Sub-agents exist for one reason: context compression.
A spawned agent can burn 150,000 tokens on research, reading files, and searching. It returns a few thousand tokens of synthesis. Your main agent's context stays lean and focused — no bloat, no attention decay, no critical constraints pushed into the noise floor.
pi install npm:pi-spawnContext windows lie. Advertised capacity is 200K tokens. Reliable attention tops out at 60–120K. Transformers have a U-shaped attention curve — information in the middle gets skimmed or ignored entirely.
Every file your agent reads, every search result it processes, pushes your actual task constraints deeper into that dead zone. Sub-agents fix this: they do the heavy lifting in isolation, then return a tight summary.
The result: your orchestrator agent holds only what it needs. First-iteration accuracy goes up. Token waste goes down.
Tell your agent to spawn a sub-agent for focused work:
Spawn a sub-agent to review
src/auth.tsfor security issues. Get a fresh perspective.
Your agent calls spawn once. A clean sub-agent reviews the file and returns findings. Your main context never sees the raw file — just the synthesis.
Spawn three sub-agents in parallel: find all model definitions, all route registrations, and all tool configurations.
Your agent fires three spawn calls in one turn. pi runs them concurrently. Results come back together — each sub-agent's noise stays in its own sandbox.
Spawn a sub-agent to research the best retry strategy for fetch, then implement it.
Agent spawns research, gets a synthesis, spawns implementation with the findings. Two isolated contexts, one clean orchestrator.
No batching API. No concurrency knob. No scheduling. Your agent calls spawn as many times as the task needs — once, N in parallel, or chained. You control the strategy.
- Same tools as your main agent (read, write, edit, bash, grep)
- Same model and credentials — plug and play
- Zero context — no history from your main session
- Your thinking level — override per spawn if needed
- No nesting — spawn is blocked inside sub-agents
pi-spawn is the minimal spawn tool. If you need persistent agent memory, cron scheduling, custom agent types, cross-agent RPC, or worktree isolation — check out @tintinweb/pi-subagents. It's excellent software.
If you want a single sharp tool that keeps your context clean — stay here.
MIT