1 The Problem — Context Bloat
The fundamental problem: as tasks get more complex, agents read a huge number of files during planning and exploration. The context window fills up — entering what Eero calls "the dumb zone" — before the agent can even begin execution.
Most of this context is exploration waste: files read to understand where things are and how they connect. Hundreds of lines of code that the agent scanned but doesn't actually need for its task. The same applies to web research — ingesting pages of content to extract a few key facts.
2 The Solution — Subagents as an Extension
The extension adds a subagents tool to Pi that spawns isolated Pi processes. Each subagent runs in its own context, does its work, and returns only the final text output to the master agent.
Key insight: most of the work being outsourced is mechanical (exploring files, fetching web pages) — it doesn't need an expensive model. The scout agent runs on Haiku (cheap), while the master uses Opus (expensive). Only the master needs to be smart.
3 Design Values
Three design principles guided the implementation:
- Capability — subagents can be as capable as you need them to be. You define their tools, model, and available sub-subagents.
- Observability — full visibility into what every subagent is doing at all times. Tool calls shown inline, one per line, expandable with
Ctrl+O. Each has its own status bar with token metrics, cost, and context window meter. Nested subagents are visually indented. - Extensibility — two layers:
- Agent loadout: each agent is entirely defined by a single markdown file. Add, remove, or modify agents by editing markdown.
- Extension code: intentionally minimal implementation. Spawns an isolated Pi process, returns final output. Easy to hack on and experiment.
4 Agent Definition — Just a Markdown File
Each subagent is entirely defined by a markdown file with YAML frontmatter:
The frontmatter defines:
name— identifier for the agentdescription— shown to the master agent when choosing which subagent to usetools— which Pi tools the subagent can accessagents— which subagents this agent can spawn (enables nesting)model— which LLM to use (Haiku for cheap work, Sonnet for medium, Opus for heavy)thinking— thinking/reasoning level
The markdown body below the frontmatter becomes the agent's system prompt. Drop a new markdown file in the agents directory and the extension auto-discovers it.
5 The Three Built-in Agents
| Agent | Model | Tools | Can Spawn | Purpose |
|---|---|---|---|---|
| Scout | Haiku (cheap) | read, grep, find, ls | None | File system exploration — find files, understand structure |
| Researcher | Sonnet (medium) | web_search, web_fetch | None | Web research — search and read pages, summarize findings |
| Worker | Sonnet/Opus | All (bash is sandboxed) | Scout, Researcher | Full coding capability — can build, test, and deploy code |
The Worker is special: it has the same capabilities as the master agent (read, write, edit, bash) but with a slightly safer bash that blocks destructive operations. Critically, the Worker also has the subagents tool — it can spawn its own Scouts and Researchers.
6 Depth Control — Preventing Infinite Recursion
Since the Worker has the subagents tool, you could theoretically have an infinite chain of Pi agents spawning more agents. The agents field in the frontmatter controls this:
- Master can spawn: Scout, Researcher, Worker
- Worker can spawn: Scout, Researcher (not other Workers by default)
- Scout/Researcher: no subagents
This creates an effective maximum depth of 3: Master → Worker → Scout/Researcher. But the system is configurable — you can enable Worker→Worker spawning by adding "worker" to the Worker's agents list in the markdown file.
7 Demo — Scout Agent
Eero launches Pi with the subagents extension and asks it to try the Scout. The Scout runs on Haiku, reads a large number of files to understand the project structure, and returns a concise summary. The UI shows:
- Live thinking in real time (Haiku's reasoning stream)
- Compact tool calls — one tool per line, expandable with
Ctrl+O - Full status bar — token metrics, cache reads/writes, session cost, context window meter
Result: the Scout used 50K tokens with Haiku = $0.15. The master agent's context stayed clean — it only received the Scout's summary.
8 Demo — Researcher Agent
The Researcher is asked to find the latest AI news about Pi. It uses web search and web fetch tools (configured in the user's Pi config), doing multiple searches and fetching several pages. Result: 70K tokens consumed by the Researcher, but the master agent stayed lean — only the summarized findings entered its context.
tools array in the Researcher's markdown file.9 Demo — Worker Building a Full App
The most impressive demo: Eero asks the master agent (Opus) to build a web UI for an audio silence cutter — a FastAPI + React app that takes audio, removes silences, and exports FCPXML for Final Cut Pro. The prompt instructs: "Once you have a plan ready, use worker sub-agents. Cut the planning to phases and delegate each phase to a worker. Don't write the code yourself. Delegate everything to workers."
The master creates a plan and delegates phases to Worker subagents. The Worker dispatches parallel workers. One Worker spawns its own Scout to understand the codebase — shown as a nested, indented subagent within the Worker's tool call. The nesting is visible:
Result: a working web app with file upload, parameter controls, and FCPXML export. The Worker even caught and fixed a bug during implementation.
10 Stress Test — 6 Nested Workers
To push the limits, Eero enables Worker→Worker spawning (by adding "worker" to the Worker's agents frontmatter) and asks the master to spawn a Worker that spawns a Worker that spawns a Worker… 6 levels deep.
Each level reports in ("Level 2 reporting in", "Level 5 spawned") and the nesting is visually indented in the terminal. All 6 levels spawn successfully and resolve their tool calls cleanly on the way back up.
11 Limitations & Future Work
Current limitation
Subagents are not interactive. You can't interfere with a subagent's session once it's spawned. Eero notes it would be very useful for subagents to have their own "ask user question" tool — allowing you to guide a subagent mid-task.
Alternative approach
Eero mentions another developer's approach: spawning subagents as separate panels in a terminal multiplexer (like Cmux), making them fully interactive. He finds it cool but prefers not to use Cmux specifically.
🎯 Key Takeaways
🔑 Key Takeaways
- Context bloat is the enemy of complex tasks — agents waste context on exploration that doesn't need to persist
- Subagents isolate context — each runs in its own Pi process, returns only the summary to the master
- Cheap models for mechanical work — Scout on Haiku ($0.15 for 50K tokens), Researcher on Sonnet, only the master needs Opus
- Each agent is a markdown file — frontmatter defines tools, model, thinking level, and available sub-subagents. System prompt in the body.
- Three built-in agents: Scout, Researcher, Worker — read-only exploration, web research, and full coding capability respectively
- Workers can spawn sub-subagents — enabling delegation chains (Master → Worker → Scout)
- Depth is configurable — control which agents can spawn which via the
agentsfrontmatter field - 6-level nesting works — theoretically no cap on depth, each level is an isolated process
- Full observability — nested tool calls are visually indented, each subagent has its own metrics bar
- Limitation: no interactivity — can't interfere with subagents mid-task (future improvement planned)
- The extension itself is minimal — spawns an isolated Pi process, returns output. Easy to modify and experiment with.
🔗 Resources & Links
- pi-subagents — the extension repository on GitHub