@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