pi-simple-agents

A subagent plugin for pi-coding-agent. Define reusable agents as Markdown files and call them from any pi session with the subagent tool.

Install

pi install npm:pi-simple-agents

That's it. The extension loads and registers the subagent tool.

Define an agent

Drop a Markdown file in ~/.pi/agent/agents/. The YAML frontmatter sets the name, the tools, and the model. The body is the system prompt.

---
name: scout
description: Codebase explorer
tools: read, grep, find, ls
---
Explore the codebase and report findings, compressed and read-only.

Every agent in that directory shows up in the subagent tool, ready to call.

Use it

Single agent, single task:

subagent agent: "scout", task: "Find all functions that use fetch() in src/"

Or just say it:

Use the agent scout to find all the functions that use fetch in src

Parallel: several agents in one call, all results come back together:

subagent tasks: [
  agent: "scout", task: "List all .ts files in src/"
  agent: "web-scout", task: "Find the latest version of the API docs"
]

Per-call options

Both modes accept optional overrides: model, tools, skills, thinking, maxTurns, timeoutMs. They apply to that one call and beat anything configured elsewhere.

subagent agent: "scout", task: "...", model: "anthropic/claude-opus-4-8", maxTurns: 5

In parallel mode, the options go inside each task entry.

Example agents

The package ships two: scout (read-only codebase recon) and web-scout (web search). Symlink them into your agents folder to try them:

ln -s /path/to/pi-simple-agents/agents-examples/scout.md ~/.pi/agent/agents/scout.md
ln -s /path/to/pi-simple-agents/agents-examples/web-scout.md ~/.pi/agent/agents/web-scout.md

Bundled skill

invoking-subagents loads automatically with the package. It covers both modes and every override. Run /skill:invoking-subagents to read it.

Configuration

Agents are plain files, so any field can be overridden per project from settings.json without touching the .md. See docs/REFERENCE.md for the full field list and precedence rules. That file also holds the Claude Code compatibility notes: agents written for Claude Code's .claude/agents/*.md format load unchanged, and its tool names and model aliases are accepted.

Limits

Up to 8 agents per call, up to 8 running at once (default 4 concurrent).

License

MIT

---

Frontmatter fields, Claude Code compatibility, settings.json overrides, known limitations, and the live-stream and usage-footer UI live in docs/REFERENCE.md.