Pi Subagent
A lightweight subagent extension for the pi coding agent that delegates prompts to specialist agents with named session continuation and parallel execution.
Per-dimension scores and reasoning
Documentation shows deliberate safety design: empty context by default, explicit project-agent trust gating with --approve, read-only starter agent, depth/cycle guards, mode-0600 temp files; however only README/LICENSE/package. were provided — index.ts, runner.ts, etc. are absent, so none of these claims are verifiable in source, hence deductions. Sensitive-data handling is a single 0600 mention with no systematic treatment: 1. No uninstall/rollback guidance: 1. Attribution section, MIT license and copyright holder are present: 2, short of full marks without code corroboration.
Internally self-consistent: package. version, peer deps and README's Pi 0.80.5 requirement align: 2. Failure paths are documented in detail (inactivity timeout, absolute timeout, partial output preservation, stale-lock recovery) but unverified in code: 2. Dependencies are optional peers with no hard runtime deps, low availability risk: 2.
Clear layered docs for everyday users and advanced extension authors: 2. Boundaries stated (call count 1–8, output 50KB/2000 lines, named-session restrictions): 2. Trigger precision relies on description plus sessionPreference/sessionHint mechanisms — documented but unverified: 2. Environment differences covered (Unix/Windows, PI_CODING_AGENT_DIR, --no-session): 2.
Excellent information architecture separating user guide from technical reference: 3. Install notes cover npm/git/manual with a version requirement: 3. Rich examples (oracle/explore/review plus tool-API cases): 3. Standard MIT license consistent with package.: 3. Naming stable but no compatibility policy: 2. Limitations scattered rather than a dedicated section: 2. Version 3.0.3 with no CHANGELOG or release history: 1. No maintainer/contribution/support statements: 1.
Uniform output wrapper (per-call statuses plus counts) and overflow handling are well documented but unverified: 2. Differentiators are named sessions and delegation guards among many Pi subagent extensions — moderate marginal value: 2. Lightweight, zero runtime deps; cost is inherent child-process overhead plus documented parent-snapshot clone expense: 2.
Core claims (process isolation, session locks, depth guards, trust gating) cannot be traced to any provided implementation: 1. README cross-corroborates with package. (name, version, repo, license, peers): 2. Docs reasonably separate defaults, configurables and advisory hints: 2.
- This is a static review based only on README/LICENSE/package.; security claims (isolation, locks, guards) are unverified — inspect index.ts and runner.ts manually before adoption.
- Project agent files are repo-controlled configuration executing with the same authority as user agents; review the model and tool allowlist of any example (e.g. oracle.md) before copying it.
- initialContext: parent carries the full authority of the parent conversation; use only when genuinely required.
- No CHANGELOG or maintainer statements — verify 3.x compatibility yourself; a killed process may require manual removal of the session lock directory.
- Named sessions require a persisted parent session; under --no-session delegation silently degrades to ephemeral calls — design workflows accordingly.
What does this agent do, and when should you use it?
Pi Subagent (mjakl/pi-subagent, MIT licensed) is an extension for the pi coding agent that lets the main agent delegate prompts to specialized subagents for tasks like code review, codebase exploration, or test auditing. Subagents are defined as Markdown files with YAML frontmatter in ~/.pi/agent/agents/*.md or project-level .pi/agents/*.md, and a read-only starter 'explore' agent is auto-created if none exist. Each subagent runs in its own isolated pi process using Pi's headless RPC mode, with no shared state with the parent or sibling subagents. The extension supports one or up to eight parallel calls via a single unified tool, named persistent sessions that survive across turns, per-call model overrides, and runtime safety mechanisms including depth and cycle guards, an inactivity watchdog, and streaming TUI rendering.
On startup the extension discovers agent definitions and lists them in the main agent's system prompt. The main agent delegates via a tool named 'subagent' that accepts a calls array (1–8 calls), each with agent, prompt, and optional model, cwd, initialContext (empty/parent), session, inactivityTimeout, and timeout. Each child runs in a separate pi process started with PI_OFFLINE=1, inheriting or overriding model, thinking level, and tool allowlists (e.g. tools: read,grep,find,ls or noTools: true) from the agent frontmatter. Named sessions derive an opaque child session ID from pi-subagent/v1 + parent session ID + effective cwd + agent name + session handle, guarded by a cross-process session lock. Results return in a uniform wrapper (e.g. '2/2 succeeded') capped at 50KB/2000 lines with overflow written to a mode-0600 temp file. Delegation guards enforce a max depth (default 3) and cycle prevention (default on), propagating PI_SUBAGENT_DEPTH and related env vars to child processes.
- A developer reviewing the current diff in pi delegates to a review subagent configured with thinking: high for correctness and regression-risk analysis
- Exploring an unfamiliar codebase: use the explore subagent to locate where a feature like authentication is implemented and return summaries with file/line references
- Multi-step specialist work (e.g. API change review) continues the same expert context across turns via a named session such as session: api-review
- Running multiple analyses simultaneously (review plus testing-audit) in one parallel subagent call instead of sequential back-and-forth
- Teams share repo-controlled specialist configs via .pi/agents/*.md, gated behind Pi's explicit project trust store
- Assigning a stronger default model (e.g. anthropic/claude-sonnet-4) to a specific agent via frontmatter or a per-call model override
What are this agent's strengths and limitations?
- One unified tool interface handles both single delegation and up to eight parallel calls, so the main agent needs no separate extension for concurrency
- Named persistent sessions (via derived session IDs and a cross-process session lock) enable multi-turn expert conversations that reuse the same review or exploration context
- Comprehensive runtime safety: depth guard (default 3), cycle prevention, and per-call overridable inactivity watchdog plus absolute timeout against runaway recursion and silent hangs
- Agents are plain Markdown files layered user/project, with project agents activated only after explicit trust records — untrusted repos cannot auto-enable them
- Fine-grained context control: subagents start fresh by default, and parent snapshot cloning requires explicit initialContext: parent, reducing cost and authority leakage
- Hard dependency on the pi coding agent runtime (0.80.5+); it cannot run directly inside other agent frameworks such as Claude Code or Codex
- Each subagent spawns a separate pi process, adding startup and RPC overhead per delegation; initialContext: parent cloning is explicitly documented as expensive
- Model-facing output is capped at 50KB/2000 lines, requiring retrieval of full summaries from a temp file or the expanded TUI on overflow
- A force-killed long-running child can leave a stale session lock that the user must manually verify and remove
- Named persistent sessions require a persisted parent pi session; they are unavailable with --no-session or from temporary parent-seeded subagent sessions
- Beyond the repository's own documentation, there is no independent adoption data, benchmarking, or community-scale evidence
How do you install or deploy this agent?
Prerequisite: Pi 0.80.5 or newer. Install via one of three methods:
1) npm (recommended): pi install npm:@mjakl/pi-subagent
2) Git: pi install git:github.com/mjakl/pi-subagent
3) Manual: cd ~/.pi/agent/extensions && git clone https://github.com/mjakl/pi-subagent.git && cd pi-subagent && npm installOn first run, if no agents exist, the extension auto-creates a starter explore.md in the user agents directory. Optional: install the packaged oracle.md example by copying agents/oracle.md into your user agents directory after reviewing its model and tool configuration.
How do you use this agent?
After installation, use pi normally: ask for work suited to a specialist (e.g. 'review this diff' or 'find where authentication is implemented'), and the main agent decides when to delegate, runs the subagent, and folds results back into your conversation — no manual subagent calls, JSON, or direct tool interaction needed. Progress streams in the TUI with expandable details. To customize specialists, write Markdown agent files with YAML frontmatter (name, description, plus optional model, thinking, tools, sessionPreference, etc.) in ~/.pi/agent/agents/*.md or .pi/agents/*.md; the Markdown body becomes the agent's extra system prompt. Advanced users can tune recursion via --subagent-max-depth or PI_SUBAGENT_MAX_DEPTH.
How does this agent compare with similar options?
The README acknowledges 'many subagent extensions for Pi' and credits vaayne/agent-kit and mariozechner/pi-mono as inspirations, without a feature-by-feature comparison; its stated differentiators are the small surface area combined with named sessions and delegation guards.