pi-agent-squad

pi-sub-agent

Minimal fork-only subagent extension for Pi coding agent.

Delegates tasks to specialized subagents running as isolated pi processes. Each subagent receives a forked snapshot of the current session context.

Features

• Fork mode only — subagents always receive your current session context
• Single agent invocation — one agent per call, no parallel tasks
• Depth guards — configurable max delegation depth (default: 3)
• Cycle prevention — blocks recursive delegation chains
• Agent discovery — reads agent definitions from ~/.pi/agent/agents/ and .pi/agents/
• TUI rendering — rich collapsed/expanded display in interactive mode

Installation

pi install /path/to/pi-sub-agent

Or add to ~/.pi/agent/settings.json:

{
  "packages": [
    "./path/to/pi-sub-agent"
  ]
}

Agent Definitions

Create .md files in ~/.pi/agent/agents/ or .pi/agents/:

---
name: explore
description: Repository exploration specialist
tools: read, grep, find, ls
---

You are a codebase exploration specialist. Only read, search, and analyze.

Usage

{ "agent": "explore", "task": "Find all authentication-related code" }

Configuration

Flags (passed to parent pi process):

• --subagent-max-depth <n> — Maximum delegation depth (default: 3)
• --subagent-prevent-cycles — Block cyclic delegation (default: true)
• --no-subagent-prevent-cycles — Disable cycle prevention

Environment variables (propagated to child processes):

• PI_SUBAGENT_DEPTH — Current depth
• PI_SUBAGENT_MAX_DEPTH — Max allowed depth
• PI_SUBAGENT_STACK — JSON array of ancestor agent names
• PI_SUBAGENT_PREVENT_CYCLES — "1" or "0"

License

MIT