@amyrsaalehi/pi-agent-team

Specialist agent teams for pi, adapted from IndyDevDan's agent-team extension.

The main agent becomes a dispatcher: it delegates through dispatch_agent instead of reading or editing files itself. Specialists run as child pi processes, with their own sessions and a live terminal dashboard.

Install

Requires Node.js >=22.19.0 and current @earendil-works/pi-coding-agent (targeted/tested version: 0.85.1). The pi executable must be on PATH.

After the package is published:

pi install npm:@amyrsaalehi/pi-agent-team

Restart pi, then try:

/agents-list
/agents-team
/agents-grid 2

Have scout inspect this project, builder implement the requested change,
and reviewer check the result.

No project setup is required: default agent definitions ship with the package. Use pi config to disable the extension when you want pi's normal tools back. Do not enable this package together with the original agent-team extension.

Commands and tool

• /agents-team: choose the active team.
• /agents-list: show active specialists and their status.
• /agents-grid <1-6>: set dashboard column count.
• dispatch_agent({ agent, task }): delegate a focused task to an active specialist; returns its result. The model calls this tool automatically.

The extension deliberately limits the main agent's active tools to dispatch_agent. Specialist tools come from each agent's definition.

Project customization

Reviewed, trusted projects can provide agent Markdown files in agents/, .claude/agents/, or .pi/agents/, plus .pi/agents/teams.yaml. Project definitions override bundled defaults by name. Untrusted project configuration is ignored. Reload/restart after configuration changes.

Example .pi/agents/scout.md:

---
name: scout
description: Read-only project exploration
tools: read,grep,find,ls
---
Inspect the project. Report relevant paths and findings. Do not modify files.

Example .pi/agents/teams.yaml:

project:
  - scout
  - builder
  - reviewer

Keep the simple top-level team/list syntax above. Agent tool names must be built-in pi tools: child extensions are disabled. Agent definitions are prompt and tool configuration, not separately installed pi skills.

Sessions and limitations

• Specialists use the dispatching project's working directory and selected model. Configure provider authentication in the child pi CLI environment.
• Child extensions are disabled to prevent recursive delegation. Providers or tools registered only by other extensions are therefore unavailable.
• Child conversations live under .pi/pi-agent-team/sessions/, isolated by parent session. Repeated dispatches can reuse specialist context. Existing sessions are not deleted on startup.
• Add .pi/pi-agent-team/ to your project's .gitignore. Session files can contain prompts, code, and sensitive tool output; do not publish them.
• Agent output is bounded. Long results are truncated rather than filling the main agent's entire context.
• Different specialists share the same checkout. Delegate independent work only; this is not worktree isolation or automatic merge/conflict management.

Security

Extensions and child agents run with your system permissions. Agents with bash, write, or edit can change files or execute commands. Tool allowlists and dispatcher prompts are not a sandbox. Review project agent definitions before trusting them. Child processes disable extensions, so permission or sandbox extensions loaded in the parent do not protect child runs. Use an external sandbox or container when isolation is required.

Child model calls may incur additional provider charges. Cancellation requests stop child processes but cannot undo file changes or remote side effects.

Development

npm ci --ignore-scripts
npm run check
npm run check:package

Source TypeScript ships directly; no compilation/build output is required. Tests run locally without paid model calls. Runtime assets are allowlisted in package.json; development tooling and generated sessions are not published.

License

MIT. Original copyright (c) 2026 IndyDevDan retained in LICENSE. See NOTICE.md for upstream revision and adaptation details.