pi-fast-subagent

In-process subagent delegation for pi with max visibility.

Runs subagents with createAgentSession() in same process instead of spawning pi subprocesses. This removes subprocess cold-start and reuses pi auth/model registry.

Features

• Single mode: { agent, task }
• Parallel mode: { tasks: [...] }
• Background mode: { agent, task, background: true } — fire-and-forget with poll/cancel
• Slash commands for background job status + cancellation via selector UI
• Per-call model override
• User + project agent discovery
• Project agents override user agents
• Max nesting depth guard
• Streamed prompt preview while the parent LLM is writing the subagent task
• Chronological expanded view (Ctrl+O): subagent tool calls and response text interleaved in execution order
• Collapsed view shows response + trailing tool calls as an indented tree

Settings

Configure preview sizes in ~/.pi/agent/settings.json or .pi/settings.json:

{
  "fastSubagent": {
    "previewLines": 12,
    "promptPreviewLines": 12
  }
}

• previewLines — response text preview lines in collapsed view (default 12)
• promptPreviewLines — task/prompt preview lines in collapsed view (default 12)

Install

pi install /absolute/path/to/pi-fast-subagent

Or from npm after publish:

pi install npm:pi-fast-subagent

Package contents

This package exposes one pi extension:

• ./index.ts — registers subagent tool

Included agents

This package bundles default agents:

• scout — code exploration specialist
• general — general-purpose helper

Discovery priority:

1. bundled package agents
2. ~/.pi/agent/agents/
3. nearest .pi/agents/
4. nearest legacy .agents/

User and project agents override bundled agents with same name.

Example override agent file:

---
name: scout
description: Explore codebases and summarize findings
model: anthropic/claude-haiku-4-5
---

You are code exploration specialist. Read relevant files, trace data flow, summarize findings clearly.

Agent frontmatter

| Field | Required | Description | |-------|----------|-------------| | name | yes | Unique agent identifier used in subagent({ agent: "..." }) | | description | yes | One-line description shown in /fast-subagent:agent | | model | no | Model override, format provider/model-id (e.g. anthropic/claude-haiku-4-5) | | tools | no | Tool allowlist (see below) | | maxDepth | no | Nested subagent depth this agent may spawn. Default 0 means this agent cannot call subagent. |

tools: field

Controls which tools the subagent has access to. The default is all tools — builtins plus parent extensions (web_search, fetch_content, mcp, playwright, …). Agents opt into lean mode with tools: builtins or an explicit built-in allowlist.

| Value | Behavior | |-------|----------| | (omitted) | Builtins + every parent extension (default) | | all | Same as omitted — explicit "everything" | | builtins | Builtins only — read, bash, edit, write, grep, find, ls | | none | No tools at all — pure reasoning agent | | comma list | Allowlist; extensions auto-load only if any listed tool is non-builtin |

Built-in tools: read, bash, edit, write, grep, find, ls.

Examples:

---
name: writer
description: Pure-reasoning writing assistant
tools: none
---

---
name: scout
description: Read-only code explorer
# drop `edit` and `write` so the agent cannot mutate the codebase
tools: read, bash, grep, find, ls
---

---
name: researcher
description: Web research agent
# listing `web_search` triggers extension loading; `read` + `write` keep the rest local
tools: read, write, web_search, fetch_content
---

---
name: general
description: Do-anything helper
# `tools` omitted means all tools; `tools: all` is equivalent
tools: all
---

Performance note: omitted tools / tools: all loads every installed pi extension into the subagent session. That adds startup cost (extension init, possibly MCP server spawn, playwright runtime, …) and token cost (bigger system prompt). Use tools: builtins or list specific tools for tight, focused agents.

YAML comments (# …) are allowed inside the frontmatter — handy for documenting why a particular tool set was chosen. See agents/general.md and agents/scout.md for examples.

maxDepth: field

Subagents cannot spawn other subagents by default, even when tools exposes the subagent tool.

---
name: planner
description: Can delegate one level deeper
maxDepth: 1
---

Depth counts nested generations from that agent:

| Value | Behavior | |-------|----------| | (omitted) / 0 | This agent cannot spawn subagents | | 1 | This agent may spawn subagents, but those children cannot spawn again unless their own maxDepth allows it | | 2 | Allows two nested generations, subject to each child agent's own maxDepth |

Aliases accepted: max_depth, depth, subagentDepth.

Background Agents

Every foreground subagent can be moved to background at any time. Background jobs run concurrently while you continue chatting. When a job finishes, pi automatically posts the result as a follow-up message.

Status bar

While a foreground subagent is running, the pi status bar shows:

{agent-name} running · Ctrl+Shift+B to move to background

While background jobs are running:

⧗ N bg agents

Moving to background

Keyboard shortcut (while subagent is running):

Ctrl+Shift+B

Slash command:

/fast-subagent:bg fg_ab12cd34

Via tool call:

subagent({ action: "detach", jobId: "fg_ab12cd34" })

Auto-completion announcement

When a background job finishes, pi injects a follow-up message automatically:

Background subagent ✓: sa_ab12cd34 (scout, 4.2s)
> Explore src and summarize architecture

<result output>

Failed jobs are announced the same way with ✗ and the error message.

Slash Commands

/fast-subagent:agent

List all available agents:

/fast-subagent:agent

Show details for a specific agent (description, file path, model, tools, system prompt):

/fast-subagent:agent scout

Tab-completion is supported for agent names.

/fast-subagent:bg

Detach a running foreground subagent to background. Each foreground job has a fg_ prefixed ID shown in the status bar.

/fast-subagent:bg fg_ab12cd34

Omit ID to list all active foreground jobs:

/fast-subagent:bg

/fast-subagent:bg-status

Open selector UI showing all active background jobs. Arrow keys to navigate, Enter to view full details.

/fast-subagent:bg-status

Skip the selector — show details for a specific job directly:

/fast-subagent:bg-status sa_ab12cd34

/fast-subagent:bg-cancel

Open selector UI to choose a running job to cancel:

/fast-subagent:bg-cancel

Cancel a specific job directly:

/fast-subagent:bg-cancel sa_ab12cd34

Keyboard Shortcuts

| Shortcut | Action | |---|---| | Ctrl+Shift+B | Move active foreground subagent to background |

Roadmap

Goal: keep this extension small and focused — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.

• UI/UX polish — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
• ~~Background subagents~~ ✔ shipped in v0.4.0 — fire-and-forget with background: true, poll/cancel/detach support

Notes

• Async/background isolation not supported in-process
• Git worktree isolation not supported
• Nested subagent spawning disabled by default (maxDepth: 0); opt in per agent via frontmatter

Tool Reference

These are subagent tool call examples used by the LLM internally. Not typically invoked directly by users.

List / discover agents

// List all agents
subagent({ action: "list" })

// Get details for a specific agent
subagent({ action: "get", agent: "scout" })

// Scope filter: "user" | "project" | "both" (default)
subagent({ action: "list", agentScope: "project" })

Single

subagent({ agent: "scout", task: "Explore src and summarize architecture" })

Parallel

subagent({
  tasks: [
    { agent: "scout", task: "Map auth flow" },
    { agent: "scout", task: "Map navigation" }
  ],
  concurrency: 2  // default: 4
})

// Repeat one task N times
subagent({ tasks: [{ agent: "scout", task: "Explore src", count: 3 }] })

Background

// Fire-and-forget — returns job ID immediately
subagent({ agent: "scout", task: "Explore src", background: true })
// → { jobId: "sa_ab12cd34", status: "running" }

subagent({ action: "poll",   jobId: "sa_ab12cd34" })  // check progress
subagent({ action: "cancel", jobId: "sa_ab12cd34" })  // abort
subagent({ action: "status" })                        // list all bg jobs
subagent({ action: "detach", jobId: "fg_ab12cd34" })  // move fg → bg

Options

subagent({ agent: "scout", task: "...", model: "anthropic/claude-haiku-4-5" })
subagent({ agent: "scout", task: "...", cwd: "/path/to/project" })

Publish

cd ~/.pi/agent/extensions/fast-subagent
npm publish

If package name is taken, rename name in package.json first, usually with your npm scope:

{
  "name": "@your-scope/pi-fast-subagent"
}