Pi Subagents Multi-Agent Framework
A multi-agent extension for the Pi agent harness: let one agent hand work to another, with interactive/background agents, sync/async coordination, orchestrator mode, and terminal mux support.
Evidence shows solid least-privilege design: spawning defaults to false, spawn-depth/width caps, tools/extensions/skills allowlists, background children forced --no-approve, trust-project defaults false. Sensitive-data handling scores 2 because the README explicitly documents full env inheritance including API keys with deny-env / PI_SUBAGENT_ENV_DENY as mitigation. Deductions: no user-confirmation step for launching children; task-expansion: shell executes parent task text as shell input (explicit opt-in with warnings, but still a high-risk surface); no dependency security policy (no lockfile or audit note in evidence); no rollback mechanism documented; the flags field can override safety args (documented last-wins).
Tests encode many behavioral contracts (session-mode resolution, strict name validation, malformed timeout values fail load rather than silently becoming no-limit), and failure messages include concrete remediation hints. Deductions: dependencies are loose >=/^ ranges against the pi ecosystem with no lockfile, so dependency availability cannot be statically guaranteed; runtime stability is inferred from test source only, never executed.
The power-user positioning is exceptionally explicit (five mux backends, interactive/background, sync/async, orchestrator mode, with when-to-use guidance), earning 3 for audience. Deductions: environment depends on externally installed binaries (tmux/zellij/wezterm/herdr/cmux) with only a setup-hint on failure and no full fallback path; trigger precision depends on description quality, and the docs admit backend detection can fail.
Strict naming conventions (kebab-case validation tested), a complete MIT license correctly attributing both HazAT and edxeth, one-line install, and a thorough frontmatter reference table. Deductions: the README is truncated mid-sentence in the timeout-warn-threshold section ('not a queued advisory steer'), leaving docs incomplete; no CHANGELOG file and versioning exists only as 2.9.0 in package.; no FAQ or bundled examples (only an external gist link); maintenance responsibility and update path are unstated (publisher unverified); the README mixes in Discord promotion and discount marketing.
Output usability is well handled: context-usage reporting, wrap-up markers that stop the parent misreading an instructed early stop as failure, resume-blocking to avoid wasted turns. Orchestrator mode targets a real multi-agent waste problem, so marginal value is plausible. Deductions: no cost guidance for expensive paths (best-of-N verifier, parallel children); actual effectiveness is unverified — no executed run backs the claims.
Most claims trace to concrete frontmatter fields with matching test assertions (spawning default, background --no-approve, name validation); risk warnings (env inheritance, shell expansion) are clearly separated from facts. Deductions: the README cites external authorities (Anthropic COORDINATOR_MODE, OpenAI Codex issues, the ADCS spec) as design corroboration that cannot be cross-checked within this evidence set; orchestrator/verifier behavior cannot be checked against the provided source (src not included), resting on test/documentation agreement only.
- Children inherit every parent environment variable including API keys/tokens; without deny-env or PI_SUBAGENT_ENV_DENY, secrets flow into child processes — especially risky with agent files authored by third parties.
- task-expansion: shell executes parent task text as shell input; enable only on agents whose task content you fully trust.
- The flags field can override generated args including --approve/--no-approve (last-wins), an escape hatch around safety defaults; audit any third-party agent file's flags carefully.
- The README is truncated mid-section at timeout-warn-threshold; documentation is incomplete — read source before relying on that feature.
- No CHANGELOG and an unverified publisher: diff-check before upgrading; the README mixes community marketing with product docs, so read critically.
- Analogies to Anthropic COORDINATOR_MODE, Codex issues, and the ADCS spec are author argumentation, not verifiable within this repository's evidence; do not treat them as adoption grounds.
What does this agent do, and when should you use it?
pi-subagents is a multi-agent extension for the Pi agent harness, forked from HazAT/pi-interactive-subagents and heavily refactored. It lets a parent agent delegate tasks through a subagent tool to named child agents defined in Markdown files with YAML frontmatter; each child runs as a separate Pi process. Children can open as visible panes in Herdr, cmux, tmux, zellij, or WezTerm, or run headlessly as background pi -p processes; launches can be async (result arrives later) or sync (parent blocks). Orchestrator mode restricts the parent session to delegation only by removing read/bash/edit tools and replacing the system prompt. The framework also provides child lifecycle management (auto-exit, subagent_done, caller_ping, subagent_resume), forked sessions that copy parent context, timeout and context-window guards, nested spawning controls, and an LLM-as-a-Verifier best-of-N mechanism built on isolated git worktrees. MIT licensed, installed via pi install.
The parent agent calls the subagent tool (requiring a name and title) to launch a child. Agent definition files live in .pi/agents/ or ~/.pi/agent/agents/; frontmatter controls mode (interactive/background), asynchrony (async), model and thinking level (model/thinking, allow-model-override, allowed-models), tool and skill allowlists (tools, deny-tools, skills, inject-skills), environment variables (env, deny-env), time limits (timeout, idle-timeout, timeout-warn-threshold), context warnings (context-warn-threshold), nested spawning (spawning, spawn-depth, spawn-width, visible-to), and parent-close-policy. Interactive children open in a detected or PI_SUBAGENT_MUX-forced mux; background children run as headless pi -p processes. Child results, including session paths and context usage, return to the parent, and subagent_resume can continue them. Orchestrator mode is enabled via the /subagents panel or Alt+S, or PI_ORCHESTRATOR_MODE=1, leaving only subagent, subagent_kill, and subagent_resume available. llm-as-a-verifier runs multiple attempts in parallel, each in its own git worktree, then a configured verifier model (must support OpenAI logprobs format) scores candidates against a criteria file and returns the best one.
- Multi-agent workflow users who want the parent to plan and coordinate only, delegating file reading, code edits, and test runs to named child agents — orchestrator mode enforces this split
- Parallel research: split independent research questions across async background agents whose results return later
- Verify-after-write cycles: use llm-as-a-verifier to attempt implementations in parallel git worktrees and let a verifier model pick the best change
- Risk control for long tasks: configure timeout/idle-timeout and context-window warnings so runaway children stop before burning tokens or overflowing context
- Terminal power users: supervise each interactive child live in a labeled pane in tmux, zellij, Herdr, cmux, or WezTerm
- Tasks needing inherited context: use fork session mode so a child sees decisions and prior results from the parent transcript
What are this agent's strengths and limitations?
- Extremely fine-grained configuration: dozens of frontmatter fields precisely control a child's model, tools, skills, environment variables, timeouts, and nesting permissions
- Orchestrator mode, modeled on Claude Code's COORDINATOR_MODE, forces the parent to coordinate only via tool restriction and prompt replacement, avoiding two agents racing each other
- llm-as-a-verifier provides a complete best-of-N implementation with git worktree isolation plus an independent verifier model scoring
- Auto-detects five terminal muxes; interactive children run in labeled visible panes, and a TUI widget shows live child status and context usage
- Tightly coupled to the Pi agent harness ecosystem; non-Pi users cannot use it directly
- Interactive children require a supported terminal mux (Herdr, cmux, tmux, zellij, WezTerm) or launch fails
- llm-as-a-verifier requires a verifier backend returning OpenAI logprobs — Anthropic and most proxies/aggregators do not work — and a 3-candidate run makes about 72 API calls, so budget accordingly
- The docs state explicitly that tool/extension restrictions are not a sandbox; untrusted code needs OS or container isolation
- Large configuration surface (many env vars and frontmatter fields) creates a steep learning curve
How do you install or deploy this agent?
Requires the Pi agent harness. Run:
bash
pi install git:github.com/edxeth/pi-subagentsTo run interactive subagents, start pi inside Herdr, cmux, tmux, zellij, or WezTerm. The repository description does not list other runtime dependencies (such as a Node.js version); verify against the repository before installing.
How do you use this agent?
- Create a Markdown agent file under your project's .pi/agents/ or global ~/.pi/agent/agents/, e.g. scout.md:
md
---
name: scoutdescription: Inspect the codebase and report the relevant files.
mode: background
auto-exit: true
tools: read,grep,find,ls
---You are a codebase scout. Find the relevant files and return a concise map.
- In a Pi session, have the parent call the subagent tool naming that agent, or press Alt+S to open the /subagents panel. Interactive agents open a pane in your current mux; background agents run headlessly.
- Optional:
export PI_ORCHESTRATOR_MODE=1to make the parent delegation-only; setPI_SUBAGENT_MUX=tmuxto force a specific mux. - Use subagent_resume to continue child sessions, subagent_kill to stop running children, and the /subagents panel to monitor status.
How does this agent compare with similar options?
The README positions the project against Anthropic Claude Code's COORDINATOR_MODE: the same mechanism of a restricted tool set, replacement system prompt, and worker isolation. The difference is that pi-subagents runs on the Pi agent harness and adds visible terminal panes, forked sessions, and LLM-as-a-Verifier.