pi-subagents

pi-subagents is a highly curated multi-agent framework for Pi agent harness.

It began as a fork of HazAT/pi-interactive-subagents, then grew into a monumental refactor: named agents, interactive panes, background workers, async parallelism, blocking agents, child-to-parent communication, forked context, a beautiful TUI widget, orchestrator mode, and much more!

Use it when one agent should hand work to another agent instead of trying to do everything in one transcript. Interactive children open in Herdr, cmux, tmux, zellij, or WezTerm; background children run headlessly.

https://github.com/user-attachments/assets/e0b97493-6c9b-4710-ba26-a6c08230ba28

Acknowledgements

Special thanks to @FasalZein and @isthatyousaf — for their contributions, ideas, and for providing access to frontier models like GPT and Claude, which made it possible to experiment and build this extension. Good guys, I owe them a lot!

🌐 Join the Community

[!NOTE] Building with AI doesn’t have to be a solo grind.
Join our Discord community to meet other people exploring the latest models, tools, workflows, and ideas: https://discord.gg/whhrDtCrSS

We talk about what’s new, what’s useful, and what’s actually worth paying attention to in AI.
And if you want more than conversation, members also get access to heavily discounted AI products and services — including deals on tools like ChatGPT Plus and more for just a few dollars.

Install

pi install git:github.com/edxeth/pi-subagents

The model

A subagent is a named agent file plus a launch policy.

The agent file says who the child is and how it should run. The parent still owns the decision to launch it. The child owns the task it receives.

Two axes matter:

• interactive or background: where the child runs
• async or sync: whether the parent waits

interactive means foreground. Pi opens a visible surface through Herdr, cmux, tmux, zellij, or WezTerm. Normal launches use a backend-specific surface, such as a tab, window, split, or stacked pane.

background means headless. Pi starts a pi -p child process without opening a pane.

Async means the parent gets a “started” result and the child answer comes back later. Sync means the parent waits for the child answer before it continues.

Interactive mux backends

Interactive children open in your current terminal backend. pi-subagents supports Herdr, cmux, tmux, zellij, and WezTerm.

Start pi inside the backend you want to use. Leave PI_SUBAGENT_MUX unset to let Pi detect it, or set it to herdr, cmux, tmux, zellij, or wezterm to force one.

The backend command must exist, and Pi must be able to see the current pane or session context. If no supported backend is active, interactive launches fail with a setup hint.

Normal launches use a backend-specific surface. Herdr keeps children beside the parent while the tab has room, then uses dedicated tabs for overflow. Every Herdr child pane is labeled with its session title, such as [reviewer] Auth implementation review. Other backends may use windows, splits, or stacked panes.

Orchestrator mode

You can turn the parent session into an orchestrator — an agent that can only delegate. It spawns sub-agents, waits for results, and synthesizes answers. It cannot read files, run commands, edit code, or search the codebase itself.

PI_ORCHESTRATOR_MODE=1 pi

Export it in your shell rc to enable permanently:

export PI_ORCHESTRATOR_MODE=1

Enable that and two things change:

1. Tool restriction. Removes read, bash, edit, write, grep, find, and every other tool except subagent, subagent_kill, subagent_resume. The LLMs cannot call what they cannot see.
2. System prompt replacement. Pi's "expert coding assistant" prompt gets replaced with one that defines the orchestrator role: decompose, delegate, synthesize. The replacement preserves Pi's APPEND_SYSTEM.md content.

Children do not inherit the parent agent's role or system prompt. Each child runs as a separate Pi process with its own agent definition and prompt chain.

Why orchestrator mode exists

Models default to doing work themselves. Given the chance, they read the file, write the fix, run the test. That works for single-agent tasks. For multi-agent workflows it defeats the purpose — you pay for two agents to race each other, and the parent floods its context with execution details instead of staying focused on coordination.

Every production multi-agent framework hits this same limit. Anthropic's Claude Code has COORDINATOR_MODE with the same mechanism: restricted tool set, replacement system prompt, worker isolation. OpenAI Codex users file issues asking for a mode where the main agent "cannot execute, only delegate." The ADCS delegation chain spec encodes it as a scope-intersection invariant: each hop narrows permissions, never widens.

The research calls it brain/hands separation. The orchestrator holds the plan. Workers hold the execution context. You keep them apart because mixing them makes both worse — the orchestrator loses sight of the plan when it starts reading files, and workers get confused about their role when they see orchestrator-level strategy in their context.

When to use it

Orchestrator mode shines on tasks that decompose into parallel work: independent research questions, multiple implementation targets, verify-after- write cycles. The orchestrator defines the structure, dispatches each piece to the right agent, reads results, and writes the next round of instructions.

Simple requests do not benefit. A single sub-agent handles those faster.

Agent definitions

Agents live here:

• .pi/agents/ in the project
• ~/.pi/agent/agents/ globally, or $PI_CODING_AGENT_DIR/agents/ when that env var is set

Project agents override global agents with the same name.

A minimal agent:

---
name: scout
description: Inspect the codebase and report the relevant files.
mode: background
auto-exit: true
tools: read,grep,find,ls
---

You are a codebase scout. Find the relevant files, read enough to be useful, and return a concise map of what matters.

The description matters. Pi uses it for ambient awareness, explained next.

For a fuller example of the intended style, see the scout agent gist by edxeth. It shows the shape this package works best with: a sharp role, an explicit contract, and little room for interpretation.

Frontmatter reference

| Field | Default | What it controls | | --- | --- | --- | | name | filename | Stable agent name used by agent: "..." | | description | unset | One-line routing hint for ambient awareness | | enabled | true | Set false to hide and block the agent | | model | Pi default | Child default model, including optional thinking suffix. When unset, the child inherits the parent's model. | | thinking | model default | Child thinking level. When unset, the child inherits the parent's thinking level. | | allow-model-override | true | Whether the parent Pi session may launch or resume this agent with a different model or thinking level. Leave it alone if you want to choose models per task from the parent chat. Set false when this agent should always use the model written in its file. | | allowed-models | unset | Extra exact model refs the parent may choose when allow-model-override is enabled. The agent model is implicitly allowed and does not need to be repeated. provider/model allows any thinking level for that model; provider/model:thinking allows only that thinking level. | | cwd | parent cwd | Working directory for the child | | extensions | all | Which extension code loads in the child: all, none, or a comma-separated allowlist | | tools | all | Child tool availability: all, none, or a comma-separated allowlist of Pi tool names. Lists may include built-in, extension/custom, and protocol tools. none disables built-in tools while preserving extension/custom tools unless denied. | | deny-tools | unset | Final comma-separated tool names to remove from the child after built-in tools, extensions, and protocol tools are selected | | skills | all | Child skill availability: all, none, or a comma-separated allowlist resolved by skill name | | inject-skills | unset | Comma-separated skills to load into the child prompt before the task | | no-context-files | false | Skip trusted project context-file discovery in the child. With the default trust-project: false, Pi already ignores project-local context files. | | inherit-append-system | false | Let Pi load the child's applicable global or trusted-project APPEND_SYSTEM.md file | | no-session | false | Use an ephemeral child session file and delete it after completion | | trust-project | false | Whether interactive child launches pass Pi's --approve flag and trust project-local files/settings. Background children always generate --no-approve for safety; use flags only as an explicit advanced override. | | auto-exit | false | Close the child after a normal completion | | system-prompt | task body | append adds the agent body to the child's own Pi system prompt (Pi's default unless the child has an applicable SYSTEM.md); replace replaces that base prompt with the agent body. The parent agent's system prompt is never inherited. | | session-mode | lineage-only | standalone, lineage-only, or fork | | flags | unset | Extra CLI flags passed to the child pi process (e.g. --verbose or --some-custom-flag). Appended after all generated args — last-wins semantics against conflicting generated args, including --approve / --no-approve. Use only as an advanced