@jerryan/pi-subagent-tools

A minimal pi extension for delegating work to isolated subagent processes. Three tools, one job each. The agent is a project manager — delegate by default, dive in only when necessary.

What makes this different?

Every subagent is a fresh pi process with an isolated context window. No agent definitions to write, no configuration files to maintain, no mode-switching parameters to misconfigure. Each tool's name is the contract:

• review — always read-only, always in the current project. You can't forget to lock it down.
• explore — always read-only, requires a target directory. Picks up the target project's settings, skills, and context.
• delegate — general-purpose worker. Inherits the parent's tools and system prompt for optimal cache reuse. Optional CWD and skills.

Installation

pi install npm:@jerryan/pi-subagent-tools

The extension is available the next time you start a pi session.

Tools

review

Review code, diffs, or files in the current project. The reviewer is always read-only — it cannot modify files or execute commands.

Parameter	Type	Required	Description
task	string	Yes	What to review
skills	string[]	No	Skills to load via --skill

explore

Map a project directory. The explorer runs in the target directory, picking up its .pi/settings.json, skills, AGENTS.md, and other context files. Always read-only.

Parameter	Type	Required	Description
task	string	Yes	What to explore
cwd	string	Yes	Target project directory
skills	string[]	No	Skills to load via --skill

delegate

General-purpose worker. No tool filtering, no system prompt override — the subagent inherits the parent's full environment, enabling cache hits when used with context inheritance (future).

Parameter	Type	Required	Description
task	string	Yes	Task to delegate
cwd	string	No	Working directory (defaults to parent's CWD)
skills	string[]	No	Skills to load via --skill
context	"fresh" | "inherit"	No	Context mode (not yet implemented)

Recursion guard

Subagents cannot spawn further subagents beyond one level:

Parent role	review	explore	delegate
Parent (normal)	✓	✓	✓
Delegate child	✓	✓	Rejects at runtime
Review / explore child	—	—	—

Related

• pi-subagents — Feature-rich implementation with agent definitions, background runs, session forking, inter-process communication, and a full management UI. The definitive reference for what's possible, though possibly more than most workflows need.
• pi-subagent-lite — Ultra-minimal (~250 lines). A single task tool with minimal context overhead.

License

MIT