### Worktree Setup Hook Example Output

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Example JSON output from the `worktreeSetupHook` indicating synthetic paths.

```json
{ "syntheticPaths": [".venv", ".env.local"] }
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

An example of agent configuration in YAML format, demonstrating various fields and their purposes.

```yaml
package: code-analysis
description: Fast codebase recon
tools: read, grep, find, ls, bash, mcp:chrome-devtools
extensions:
model: claude-haiku-4-5
fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
thinking: high
systemPromptMode: replace
inheritProjectContext: false
inheritSkills: false
skills: safe-bash, chrome-devtools
output: context.md
defaultReads: context.md
defaultProgress: true
completionGuard: false
interactive: true
maxSubagentDepth: 1
```

--------------------------------

### Installation

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Install the pi-subagents extension using npm.

```bash
pi install npm:pi-subagents
```

--------------------------------

### Prompt-template integration example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

An example of how to integrate pi-subagents with prompt templates, demonstrating the use of frontmatter to configure subagent delegation.

```markdown
---
description: Take a screenshot
model: claude-sonnet-4-20250514
subagent: browser-screenshoter
cwd: /tmp/screenshots
---
Use url in the prompt to take screenshot: $@

```

--------------------------------

### Chain File Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

A basic example of a chain file in Markdown format, including frontmatter for name and description.

```markdown
---
name: scout-planner
description: Gather context then plan implementation
---


```

--------------------------------

### Parallel Context-Build Technique Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

An example demonstrating the structure for the parallel context-build technique, showing parallel tasks for different context builders.

```typescript
subagent({
  chain: [{
    parallel: [
      { agent: "context-builder", task: "Build request/scope context for: ...", output: "context-build/request-and-scope.md" },
      { agent: "context-builder", task: "Build codebase/pattern context for: ...", output: "context-build/codebase-and-patterns.md" },
      { agent: "context-builder", task: "Build validation/risk context for: ...", output: "context-build/validation-and-risks.md" }
    ]
  }],
  context: "fresh"
})
```

--------------------------------

### Install pi-web-access

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Command to install the pi-web-access package, which is required for the researcher builtin agent.

```bash
pi install npm:pi-web-access
```

--------------------------------

### Execution Examples

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Examples demonstrating how to execute single agents, forked contexts, parallel tasks, chained tasks, background chains, fan-out/fan-in chains, and worktree isolation.

```typescript
// Single agent
{ agent: "worker", task: "refactor auth" }
{ agent: "scout", task: "find todos", maxOutput: { lines: 1000 } }
{ agent: "scout", task: "investigate", output: false }
{ agent: "scout", task: "write a large report", output: "reports/scout.md", outputMode: "file-only" }

// Forked context
{ agent: "worker", task: "continue this thread", context: "fork" }

// Parallel
{ tasks: [{ agent: "scout", task: "a" }, { agent: "reviewer", task: "b" }] }
{ tasks: [{ agent: "scout", task: "audit auth", count: 3 }] }
{ tasks: [{ agent: "scout", task: "audit frontend" }, { agent: "reviewer", task: "audit backend" }], context: "fork" }

// Chain
{ chain: [
  { agent: "scout", task: "Gather context for auth refactor" },
  { agent: "planner" },
  { agent: "worker" },
  { agent: "reviewer" }
]}

// Chain in the background, suitable for unblocking the main chat
{ chain: [...], async: true }

// Chain with fan-out/fan-in
{ chain: [
  { agent: "scout", task: "Gather context" },
  { parallel: [
    { agent: "worker", task: "Implement feature A from {previous}" },
    { agent: "worker", task: "Implement feature B from {previous}" }
  ], concurrency: 2, failFast: true },
  { agent: "reviewer", task: "Review all changes from {previous}" }
]}

// Worktree isolation
{ tasks: [
  { agent: "worker", task: "Implement auth" },
  { agent: "worker", task: "Implement API" }
], worktree: true }
```

--------------------------------

### Builtin overrides example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Example JSON configuration for overriding builtin agent settings, specifically for the 'reviewer' agent.

```json
{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "inheritProjectContext": false
      }
    }
  }
}
```

--------------------------------

### Agent and Skill Configuration Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Provides examples of how to configure agents with specific tasks and skills, including overriding or disabling skills.

```typescript
{ agent: "scout", task: "..." }
{ agent: "scout", task: "...", skill: "tmux, safe-bash" }
{ agent: "scout", task: "...", skill: false }
```

--------------------------------

### Example agent frontmatter

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Example YAML frontmatter for defining an agent, showing the 'name' field.

```yaml
---
name: scout

```

--------------------------------

### Parallel Handoff-Plan Technique Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

An example demonstrating the structure for the parallel handoff-plan technique, involving parallel research and context building followed by synthesis.

```typescript
subagent({
  chain: [
    { parallel: [
      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
      { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
      { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
    ] },
    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
  ],
  context: "fresh"
})
```

--------------------------------

### Management Actions

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Examples for managing agents and chains, including listing, getting, creating, updating, and deleting them.

```typescript
{ action: "list" }
{ action: "list", agentScope: "project" }
{ action: "get", agent: "scout" }
{ action: "get", agent: "code-analysis.scout" }
{ action: "get", chainName: "review-pipeline" }

{ action: "create", config: {
  name: "Code Scout",
  package: "code-analysis",
  description: "Scans codebases for patterns and issues",
  scope: "user",
  systemPrompt: "You are a code scout...",
  systemPromptMode: "replace",
  inheritProjectContext: false,
  inheritSkills: false,
  model: "anthropic/claude-sonnet-4",
  fallbackModels: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"],
  tools: "read, bash, mcp:github/search_repositories",
  extensions: "",
  skills: "parallel-scout",
  thinking: "high",
  output: "context.md",
  reads: "shared-context.md",
  progress: true
}}

{ action: "create", config: {
  name: "review-pipeline",
  description: "Scout then review",
  scope: "project",
  steps: [
    { agent: "scout", task: "Scan {task}", output: "context.md" },
    { agent: "reviewer", task: "Review {previous}", reads: ["context.md"] }
  ]
}}

{ action: "update", agent: "code-analysis.scout", config: { model: "openai/gpt-4o" } }
{ action: "update", chainName: "review-pipeline", config: { steps: [...] } }
{ action: "delete", agent: "scout" }
{ action: "delete", chainName: "review-pipeline" }
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Demonstrates how to configure agents like 'scout' and 'planner', including output, model, and progress settings.

```markdown
## scout
output: context.md

Analyze the codebase for {task}

## planner
reads: context.md
model: anthropic/claude-sonnet-4-5:high
progress: true

Create an implementation plan based on {previous}
```

--------------------------------

### User Interaction Menu Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/prompts/parallel-review.md

Provides an example of a numbered menu presented to the user for selecting actions after a review, when not in autofix mode.

```text
Reply with [1], [2], or further instructions:
[1] Apply only the fixes worth doing now.
[2] Apply the fixes worth doing now plus optional improvements.
```

--------------------------------

### Example Output Paths

Source: https://github.com/nicobailon/pi-subagents/blob/main/prompts/parallel-handoff-plan.md

Specifies the distinct output paths for artifacts generated by the subagents.

```markdown
Use distinct output paths under the chain directory. Example outputs:
- `handoff/external-reference.md`
- `handoff/local-context.md`
- `handoff/implementation-strategy.md`
- `handoff/final-handoff-plan.md`
```

--------------------------------

### Oracle Workflow Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Demonstrates the fork to 'oracle' for review and 'worker' for implementation after approval.

```typescript
// Advisory review in a branched thread. Oracle defaults to forked context.
subagent({
  agent: "oracle",
  task: "Review my current direction, challenge assumptions, and propose the best next move."
})

// Implementation only after explicit approval. Worker defaults to forked context.
subagent({
  agent: "worker",
  task: "Implement the approved approach: ..."
})
```

--------------------------------

### Extension Loading Examples

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Illustrates different ways to configure extension loading using the 'extensions' field in YAML.

```yaml
# Omitted: all normal extensions load

# Empty: no extensions
extensions:

# Allowlist
extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts
```

--------------------------------

### Worktree Isolation Examples

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Examples demonstrating the use of `worktree: true` for parallel agent tasks and chains.

```typescript
{ tasks: [
  { agent: "worker", task: "Implement auth", count: 2 },
  { agent: "worker", task: "Implement API" }
], worktree: true }

{ chain: [
  { agent: "scout", task: "Gather context" },
  { parallel: [
    { agent: "worker", task: "Implement feature A from {previous}" },
    { agent: "worker", task: "Implement feature B from {previous}" }
  ], worktree: true },
  { agent: "reviewer", task: "Review all changes from {previous}" }
]}
```

--------------------------------

### Staged Fix Orchestration Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

An example demonstrating the staged fix orchestration technique using a TypeScript-like syntax for subagent configuration.

```typescript
subagent({
  async: true,
  context: "fresh",
  chain: [
    { parallel: [
      { agent: "reviewer", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" },
      { agent: "reviewer", task: "Plan fixes for scheduler contract. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/scheduler.md", outputMode: "file-only" },
      { agent: "reviewer", task: "Plan fixes for sandbox/security. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/sandbox.md", outputMode: "file-only" }
    ], concurrency: 3 },
    { agent: "worker", task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\n\nPlanning summaries:\n{previous}", output: "worker/fixes.md", outputMode: "file-only", progress: true },
    { parallel: [
      { agent: "reviewer", task: "Validate the post-worker diff for deploy and scheduler fixes. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
      { agent: "reviewer", task: "Validate the post-worker diff for sandbox/security fixes. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
    ], concurrency: 2 }
  ]
})
```

--------------------------------

### Example Review Pass

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example configuration for a review pass after implementation, involving multiple reviewer agents.

```typescript
subagent({
  tasks: [
    { agent: "reviewer", task: "Review the current diff for correctness and regressions. Inspect changed files directly; do not rely on the worker's reasoning.", output: false },
    { agent: "reviewer", task: "Review the current diff for tests and validation quality against the validation contract. Inspect changed files directly.", output: false },
    { agent: "reviewer", task: "Review the current diff for simplicity and maintainability. Inspect changed files directly.", output: false }
  ],
  concurrency: 3,
  context: "fresh",
  async: true
})
```

--------------------------------

### Create an Agent

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of creating a new agent with specified configuration.

```typescript
subagent({
  action: "create",
  config: {
    name: "my-agent",
    package: "code-analysis",
    description: "Project-specific implementation helper",
    systemPrompt: "Your system prompt here.",
    systemPromptMode: "replace",
    model: "openai-codex/gpt-5.4",
    tools: "read,grep,find,ls,bash"
  }
})
```

--------------------------------

### Install pi-intercom

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Installs the pi-intercom package, which allows child agents to communicate back to the parent Pi session.

```bash
pi install npm:pi-intercom
```

--------------------------------

### Shared Task Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Demonstrates how to list agents and specify a shared task using '--'.

```text
/chain scout planner -- analyze the auth system
/parallel scout reviewer -- check for security issues
```

--------------------------------

### Example Implementation Handoff

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Illustrates a typical handoff after clarification and optional planning, showing the initiation of a 'worker' subagent.

```typescript
subagent({
  agent: "worker",

```

--------------------------------

### Parallel execution - Basic

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of initiating parallel tasks.

```typescript
subagent({
  tasks: [
    { agent: "scout", task: "Explore the auth module" },
    { agent: "reviewer", task: "Review the API client" }
  ]
})
```

--------------------------------

### Programmatic Tool Usage Example

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Demonstrates the parameters passed to the LLM when calling the 'subagent' tool.

```typescript
{ agent: "scout", task: "..." }
```

--------------------------------

### Minimal agent file example

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

A basic structure for an agent configuration file in Markdown format.

```markdown
---
name: my-agent
package: code-analysis
description: What this agent does
model: openai-codex/gpt-5.4
thinking: high
tools: read, grep, find, ls, bash
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
---

Your system prompt here.
```

--------------------------------

### Basic Async Subagent Launch

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of launching a subagent in asynchronous mode.

```typescript
subagent({
  agent: "worker",
  task: "Run the full test suite",
  async: true
})
```

--------------------------------

### Running Diagnostics

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Command to run diagnostics for subagent setup and startup issues.

```typescript
subagent({ action: "doctor" })
```

--------------------------------

### Worktree Setup Hook Configuration

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

JSON configuration for setting up a custom hook to run after each worktree is created.

```json
{
  "worktreeSetupHook": "./scripts/setup-worktree.mjs",
  "worktreeSetupHookTimeoutMs": 45000
}
```

--------------------------------

### Running a reviewer agent with a specific model

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Example of how to run a specific agent with a model override for a single execution.

```text
/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
```

--------------------------------

### Asking to check subagent and intercom setup

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Natural language query to check if subagents and intercom are correctly configured.

```text
Check whether subagents and intercom are set up correctly.
```

--------------------------------

### Session Sharing Configuration

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Example of how to enable session sharing by passing `share: true` in the agent configuration.

```typescript
{
  agent: "scout",
  task: "...",
  share: true
}
```

--------------------------------

### Example Parallel Context Builder Invocation

Source: https://github.com/nicobailon/pi-subagents/blob/main/prompts/parallel-context-build.md

Demonstrates how to launch fresh-context `context-builder` subagents in parallel for building handoff context. It specifies distinct output paths for each parallel task.

```shell
$@
context-build/request-and-scope.md
context-build/codebase-and-patterns.md
context-build/validation-and-risks.md
```

--------------------------------

### Example Fix Worker

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example configuration for a fix worker agent that applies synthesized reviewer feedback.

```typescript
subagent({
  agent: "worker",
  task: "Apply the synthesized reviewer feedback below. Only apply fixes worth doing now; preserve user-approved scope; ask before unapproved product or architecture changes. Run focused validation and summarize what changed.\n\nReviewer synthesis:\n...",
  async: true
})
```

--------------------------------

### Subagent Tool Usage

Source: https://github.com/nicobailon/pi-subagents/blob/main/prompts/parallel-handoff-plan.md

Demonstrates how to use the 'subagent' tool in chain mode for parallel processing.

```markdown
Use the `subagent` tool in chain mode:

1. First step: a parallel group.
   - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.
   - `context-builder` for local codebase context.
   - Add a second `context-builder` only when the scope is large enough to benefit from a separate implementation-strategy pass.

2. Second step: a synthesis `context-builder` that reads the parallel findings and writes the final handoff plan and meta-prompt.
```

--------------------------------

### Example invocation with a maximum of 3 review rounds

Source: https://github.com/nicobailon/pi-subagents/blob/main/prompts/review-loop.md

This demonstrates how to invoke the review loop with a specific maximum number of review rounds.

```shell
$@ review-loop --max-review-rounds 3
```

--------------------------------

### Delete an agent

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of deleting a subagent using a management action.

```typescript
subagent({ action: "delete", agent: "code-analysis.my-agent" })
```

--------------------------------

### Single agent

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of invoking a single subagent with a specific task.

```typescript
subagent({
  agent: "oracle",
  task: "Review my current direction and challenge assumptions."
})
```

--------------------------------

### Background and Forked Runs

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Illustrates how to run commands in the background ('--bg') or fork new sessions ('--fork').

```text
/run scout "audit the codebase" --bg
/chain scout "analyze auth" -> planner "design refactor" -> worker --bg
/parallel scout "scan frontend" -> scout "scan backend" --bg
/run reviewer "review this diff" --fork
/chain scout "analyze this branch" -> planner "plan next steps" --fork
/parallel scout "audit frontend" -> reviewer "audit backend" --fork
/run reviewer "review this diff" --fork --bg
/run reviewer "review this diff" --bg --fork
```

--------------------------------

### Chain execution

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of chaining multiple subagent tasks sequentially.

```typescript
subagent({
  chain: [
    { agent: "scout", task: "Map the auth flow and summarize key files" },
    { agent: "planner", task: "Create an implementation plan from {previous}" },
    { agent: "worker", task: "Implement the approved plan based on {previous}" }
  ]
})
```

--------------------------------

### Chain Execution Command

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Shows how to run a chain using a command-line interface.

```text
/run-chain scout-planner -- refactor authentication
```

--------------------------------

### Update an Agent

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of updating an existing agent's configuration.

```typescript
subagent({
  action: "update",
  agent: "code-analysis.my-agent",
  config: {
    thinking: "high"
  }
})
```

--------------------------------

### Common Workflow: Recon -> Plan -> Implement

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

An example of a common workflow for Pi subagents, demonstrating a chain of agents for reconnaissance, planning, and implementation.

```typescript
subagent({
  chain: [
    { agent: "scout", task: "Map the auth flow and summarize relevant files" },
    { agent: "planner", task: "Plan the migration from {previous}" },
    { agent: "worker", task: "Implement the approved plan from {previous}" }
  ]
})
```

--------------------------------

### Running the subagents doctor tool

Source: https://github.com/nicobailon/pi-subagents/blob/main/README.md

Command to run a diagnostic tool for subagents and intercom setup.

```text
/subagents-doctor
```

--------------------------------

### Parent Reply to Supervisor Request

Source: https://github.com/nicobailon/pi-subagents/blob/main/skills/pi-subagents/SKILL.md

Example of a parent agent replying to a contact_supervisor request.

```typescript
intercom({ action: "reply", message: "Optimize for readability." })
```