pi-rakit-subagent

Delegate focused tasks to child agents from within Pi

Packages

Package details

extension

Install pi-rakit-subagent from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-rakit-subagent

Package: pi-rakit-subagent
Version: 0.5.0
Published: Oct 6, 2026
Downloads: 263/mo · 263/wk
Author: anandamw
License: MIT
Types: extension
Size: 28.7 KB
Dependencies: 0 dependencies · 0 peers

Pi manifest JSON

{
  "extensions": [
    "./extensions"
  ]
}

Security note

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

README

pi-rakit-subagent

Delegate focused tasks to child agents from inside Pi.

Install

pi install npm:pi-rakit-subagent

Tools

Tool	Purpose
`subagent`	Run one focused task (set `background: true` to run without blocking)
`subagents`	Run several tasks in parallel
`subagent_jobs`	List background jobs and their status
`subagent_result`	Fetch the output of a background job by id

Commands

/subagent [agent] <task>     run a one-off task
/subagent-jobs               list background jobs

Ask in natural language — Pi decides when to call the tool:

Use the subagent reviewer to review this diff.
Run parallel reviewers: one for correctness, one for tests, one for complexity.

Built-in agents

Agent	Purpose	Tools
`general`	Any focused task	default
`reviewer`	Strict code review: bugs, edge cases, missing tests	read-only
`scout`	Read-only codebase investigation	read-only
`planner`	Short ordered plan with risks	read-only
`tester`	Concrete test cases and edge cases	read-only

Custom agents

Create ~/.pi/agent/subagent/agents.json (or point PI_RAKIT_SUBAGENT_CONFIG at another file):

{
  "defaultAgent": "general",
  "concurrency": 4,
  "agents": {
    "architect": {
      "label": "Architect",
      "instructions": "You design systems and call out trade-offs.",
      "tools": ["read", "grep", "find", "ls"],
      "model": "openai/gpt-4o"
    }
  }
}

agents adds or overrides roles (built-ins stay available).
tools restricts the child to an allowlist of tool names.
model selects a specific provider/model-id for that role.
defaultAgent sets the fallback role; concurrency caps parallel children.

Background jobs

Run subagent with background: true to start a job without blocking. When it finishes, the result is delivered automatically according to backgroundDelivery in agents.json:

"notify" (default) — show a custom message with the result.
"followUp" — inject the result as a user message so the model reacts.
"off" — fetch it manually with subagent_result / /subagent-jobs.

Set "backgroundTriggerTurn": true to let a notify message start a model turn. While a job runs you can keep working and submit new requests; the result arrives when it is ready.

Display

Tool calls and results render in the TUI with status icons (◆ running, ✓ done, ⏳ background), the agent and model, and a short preview. Press ctrl+e on a result to expand the full output.

Notes

Each child runs in an in-memory session in the current working directory.
Children cost tokens and time like any other model call.
Background jobs live for the current Pi session only.