@shog-lab/pi-subagent

Spawn focused sub-pi processes from inside pi. Registers a `spawn_subagent` tool: agent calls it with cwd + prompt, gets back the sub-agent's response. Fire-and-forget child pi via spawnPi. Previously bundled in @shog-lab/pi-toolkit 0.2.x.

Packages

Package details

extension

Install @shog-lab/pi-subagent from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@shog-lab/pi-subagent

Package: @shog-lab/pi-subagent
Version: 0.2.1
Published: Jul 3, 2026
Downloads: 399/mo · 15/wk
Author: shog-lab
License: MIT
Types: extension
Size: 17.4 KB
Dependencies: 2 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "dist/extensions/subagent/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@shog-lab/pi-subagent

Spawn focused sub-pi processes from inside pi.

Registers a single spawn_subagent tool. Your agent calls it with a cwd + prompt; pi-subagent spawns a clean child pi (no extensions, no inherited context), waits for it to finish, returns the response.

Useful for: isolated code analysis, parallel exploration, "classify this content without bias from my loaded context", running a focused sub-task in a different directory.

Install

npm i -D @shog-lab/pi-subagent

pnpm:

pnpm add -D @shog-lab/pi-subagent
INIT_CWD="$PWD" pnpm exec pi-subagent-init

postinstall still tries to symlink dist/extensions/subagent/ into the host repo's .pi/extensions/ for npm users. pnpm users should run the explicit init command because pnpm may block lifecycle scripts.

Tool

Tool	Args	Purpose
`spawn_subagent`	`cwd: string`, `prompt: string`, `timeout?: number` (seconds, default 300, max 600)	Spawn a child pi at `cwd` with `prompt`, return its response text and token usage

The child pi runs with --no-extensions, --no-skills, --no-prompt-templates, and --no-context-files — it's a clean slate that only sees the focused task prompt.

Why a separate package

spawn_subagent is infrastructure (child-process spawning helper), not a leaf tool like web_search. Previously bundled in @shog-lab/pi-toolkit for historical reasons; extracted in toolkit 0.3.0 so it can evolve independently and so users who want JUST subagent capability don't have to pull in mmx CLI / agent-browser deps.

Migration from @shog-lab/pi-toolkit < 0.3.0

If you previously got spawn_subagent via toolkit:

npm i -D @shog-lab/pi-subagent
# now both packages contribute: toolkit gives web_search / mcp-bridge,
# pi-subagent gives spawn_subagent

No code change needed in your agent prompts — the tool name (spawn_subagent) is unchanged.

Dependencies

{
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "^0.74.0"
  },
  "dependencies": {
    "@shog-lab/pi-utils": "*",
    "@sinclair/typebox": "^0.34.0"
  }
}

License

MIT