Pi Subagent

Delegate bounded work from Pi to independent child Pi processes. Run a single task, parallel investigations, or a sequential implementation/review chain—without creating role files first.

Each child receives its own context and explicitly selected tools. Background work has session-local task IDs, paginated results, cancellation, and a separate usage ledger.

Install

pi install npm:@mothieras/pi-subagent

Start a new session, or run /reload after the current turn finishes. Enable only one implementation of subagent / subagent_task.

This installs the tools, workflow prompts, and delegation skill. Example roles and the optional Plan Mode companion require separate setup.

The command installs the latest published npm release. Update with pi update npm:@mothieras/pi-subagent. To pin a specific release, use pi install npm:@mothieras/pi-subagent@<version>. New Git commits do not change the npm release.

Git/local installation remains supported; see installation, source migration, and release preparation. Unversioned Git installs follow the default branch and may contain unreleased changes. See the changelog for release history. This README describes the current checkout.

Start with a read-only task

Ask Pi to delegate an investigation, or call subagent directly:

{
  "task": "Map this repository's entry points and permission checks. Read-only; inspect files in this checkout only. Return paths, line numbers, and unresolved risks.",
  "config": {
    "tools": {
      "allow": ["read", "grep", "find", "ls"],
      "extensions": [],
      "mcp": []
    }
  }
}

Include the goal, necessary context, file scope, constraints, and expected deliverable. Children do not inherit the parent conversation, context files, skills, extensions, or MCP servers. Model and thinking selection inherit by default; inline configuration can override them.

Choose exactly one execution mode:

| Mode | Use it for | | --- | --- | | task | One self-contained assignment. | | tasks | Independent assignments in parallel. | | chain | Dependent steps; {previous} passes the preceding retained output. |

Optional Markdown roles make recurring assignments reusable. See the API reference for precedence, models, tool sources, and complete call examples.

Run work in the background

{
  "tasks": [
    { "task": "Inspect authentication entry points in this checkout. Read-only; return permission checks and evidence of gaps." },
    { "task": "Inspect persistence entry points in this checkout. Read-only; return failure handling and evidence of risks." }
  ],
  "config": {
    "tools": { "allow": ["read", "grep", "find", "ls"], "extensions": [], "mcp": [] }
  },
  "background": true
}

Keep the returned task ID. Uncollected completion normally wakes the parent; the notification contains metadata, not the report. Retrieve missing output separately:

{
  "action": "result",
  "taskId": "<returned-task-id>"
}

Follow the returned nextCursor until it is null. Complete final output delivery consumes pending reminders automatically; status, log, and partial reads do not. Delivery is not acceptance or verification. Already-collected output remains readable, and busy-parent reminders are rechecked and batched before settlement.

Background tasks and retained results do not survive exit, session switch, or reload. Save important findings first. Child usage appears in subagent_task list/status, not Pi's native /session totals.

Inspect activity without a model call

In the TUI, run /subagents to inspect live child activity and retained completions. It shows item state, actual start time, runtime, current tool, last-event age, and extension usage. Use arrow/Page Up/Page Down keys to scroll and Escape to close (configured selection keys are respected). The footer includes this entry point while work is active or queued.

The view is read-only: no model turn, report/log read, usage charge, or result-delivery acknowledgment. A recent event is not proof that a process is healthy. In RPC/JSON/print modes, use subagent_task list/status; those responses also expose item activity fields.

Safety boundaries

Isolation is not an OS sandbox. Tools and executable sources retain host permissions; cwd does not restrict filesystem access.

• Defaults include write-capable tools. Use an explicit read-only allowlist for investigations.
• Set config.timeoutMs to bound each child's runtime, excluding queueing. There is no built-in deadline; 0 disables an inherited limit; a timeout stops that child through normal cleanup but does not roll back changes. See runtime deadlines.
• Children receive only selected extensions/MCP sources. Untrusted project roles and executable sources require approval; no UI does not imply approval.
• Shared-worktree parallel writers require explicit consent. Prefer separate worktrees or sequential implementation/review; this extension creates neither worktrees nor merges.
• Verify child output before integration. Completion messages grant no permissions, and cancellation does not roll back changes.

See the permission contract and security policy.

Compatibility and verification

The development host baseline is Pi 1.1.0 / Node.js 24. CI targets Linux and macOS with local fake providers/MCP servers; green runs establish automated coverage, not universal platform or provider support.

Manual macOS smoke tests covered Terminal/Ghostty TUI, lifecycle cleanup, and read-only background delegation with openai-codex/gpt-6-luna. Windows whole-system behavior, other provider/subscription flows, and broader interactive configurations remain unverified.

Documentation and contributing

| Need | Read | | --- | --- | | Setup, roles, Plan Mode, upgrade, or rollback | Installation | | Parameters, precedence, permissions, lifecycle, usage, or limits | API reference | | Agent-facing delegation guidance | Delegation skill | | Report a bug, propose a change, or run development checks | Contributing | | Repository rules for coding agents | AGENTS.md | | Release history | Changelog |

Contributions are welcome. Start with a small, reproducible issue or focused PR; discuss public-contract or permission changes before implementing them. Tool summaries retain call essentials and safety boundaries; detailed orchestration guidance lives in the on-demand skill. /skill:pi-subagent <task> explicitly loads the installed guide.

License and attribution

MIT. Derived from the official subagent example in @earendil-works/pi-coding-agent 1.1.0, with upstream attribution retained. This repository maintains an independent implementation; the original example README is archived for provenance.