Minimal subagents for pi, where each subagent is a regular pi session with the same tools and access as your agent, rather than task-specific restricted subagents.
Scripted demo with real pi sessions and tools; model names are illustrative.
Install
pi install npm:pi-basic-subagents
Design
Just a pi session. Each subagent runs in your project with your settings, extensions, MCP servers, skills, and AGENTS.md, and its transcript is a normal pi session you can open.
Minimal. No agent definitions, prompts, or tool lists to write: install it and ask your agent to delegate. It exposes three tools for your agent, modeled on Claude and Codex so models already know them. No commands, skills, or additions to your agent's system prompt; subagents get a few lines telling them how to work and report. No workflow engine: your agent scripts subagents with codemode.
Never blocking. Your agent starts a subagent and can steer or stop it while it works; the subagent reports back when it finishes. Your agent stays free to talk to you.
Use
Ask for it in plain words; your agent calls the tools:
Have a subagent research the best queuing approach while you fix the failing test.
Have two subagents review this work, one using Opus and one using GPT, and compare what they find.
Starting a subagent returns right away, so you can keep talking to your agent. Running subagents show live above the editor with their model, context size, and time. When one finishes, its report lands in your conversation and wakes your agent. Your agent can steer running subagents, or resume finished ones, by sending them messages. With codemode, it can also script many subagents and pass on only what matters.
There are no subagent types: your agent's prompt carries any constraints, such as not changing anything. A subagent uses the same model as your agent unless your agent picks another.
To steer subagent usage and model choices, add guidance to your AGENTS.md, for example:
## SubagentsDelegate to subagents only when asked. Choose model and thinking level by task:- Complex implementation or research: `gpt-6.1-sol:medium`- Well-specified edits to 1–3 files: `gpt-6-luna:low`- Reviews: `claude-opus-5-5:high` or `gpt-6.1-sol:high`
Configuration
Optional. Set any of these under basicSubagents in ~/.pi/agent/settings.json, or in .pi/settings.json in a trusted project, which overrides it per setting:
{ "basicSubagents": { "maxConcurrent": 5 }}
Setting
Default
Description
maxConcurrent
20
How many subagents can run at once per session.
maxDepth
1
How many layers of subagents are allowed below your session. At 1, subagents can't start their own.
inside your pi process (foreground) or a separate runner (background)
inside your pi process
inside your pi process
its own pi process
Gets your extensions, MCP, skills, AGENTS.md
yes
depends on agent and mode
yes; AGENTS.md only in general-purpose
your conversation and tools; no skills or AGENTS.md
yes
Setup
none
none (7 built-in agents)
none (3 built-in agents)
none (6 built-in agents)
agent files and symlinks
Custom agents, per-agent tools and model
FAQ
Why is there no tool for my agent to wait for subagents?
So you can keep talking to your agent. Given a wait tool, models tend to call it right after starting subagents, shutting you out until they finish; Claude Code removed its wait tool for the same reason (research memo). Waiting happens only in codemode scripts, which get subagent_start_and_wait: like await agent() in Claude Code's workflows, it returns the subagent's report, so a script can fan out with Promise.all and return only what your agent needs. Stopping a script (Esc) stops the subagents it's waiting on, and calls past maxConcurrent fail, so batch big fan-outs.
Why one-way communication? What if a subagent gets stuck?
A subagent works in the background, where nobody is watching to answer questions, and your agent, busy with its own work, is a poor stand-in. So a subagent makes routine judgment calls itself and states its assumptions in its report. At a decision that would change the outcome, it stops and reports what needs deciding. Your agent, or you through it, answers with a message, which resumes the subagent with its full history.
Can a subagent be read-only?
Only by instruction. Your agent can tell it not to change anything, but it has the same tools as any pi session, and read-only work often needs bash, which can edit any file. For enforced limits, use a sandbox or a permission system.
Can two subagents work on the same files?
They can, and they can collide: subagents work in your project directory, not a copy, so that your project's settings and trust apply to them. Give parallel subagents separate files, or ask for isolation when you delegate: a subagent can create a git worktree and work there.
Can I see what a subagent did?
Expand its report for the transcript path. Each finished report is also saved as a Markdown file next to the transcript. pi --session <path> opens it; to continue the work yourself, use pi --fork <path>, which leaves the original for your agent to resume.
What happens to running subagents when I quit pi?
They're stopped (so are they on /reload, /new, and /resume). When you reopen the session, your agent hears which ones were cut short and where any missed reports are, and can resume them with a message.
Learn more
docs/spec.md: exactly how the tools and subagents behave