Agent Reference

Pi ships 30 specialist agents in agents/. Each one is a markdown file with YAML frontmatter (name, description, tools) followed by a system prompt. This page lists every bundled agent, what its description says, and how the orchestrator decides which one to use.

Specialists are meant to be delegated to, not imitated. The orchestrator reads the routing rules, spawns the matching specialist through the subagent tool, and merges the result — it does not do the specialist's job inline.

Note: None of the bundled agents pin a model or provider in their frontmatter. Every agent runs on whatever model the session resolves to, unless you override it per call or through agent_overrides in settings.

How routing works

Routing is defined in rules/10-agent-routing.md, not by the model guessing from agent names. Three layers:

1. Domain-to-agent table. File types and tools map to a named agent — .py → python-expert, .go → go-expert, JS/TS/React/Vue/Angular → ts-expert, .java → java-expert, .sh → bash-expert, .md → technical-documentation-writer, Docker → docker-expert, Kubernetes/OpenShift → kubernetes-expert, Jenkins/CI/Groovy → jenkins-expert, local git → git-expert, GitHub (PRs, issues, releases, workflows) → github-expert, unresolved merge/rebase conflicts → conflict-resolver, external library docs → docs-fetcher, running or analyzing tests → test-runner, writing tests → test-automator, debugging → debugger, API docs → api-documenter, external-repo security audit → security-auditor.

2. Intent overrides the tool. The same file type routes differently by goal: running existing Python tests → test-runner; fixing Python production code after failures → python-expert; creating or changing Python tests → test-automator; editing Python production files → python-expert even via sed/awk; creating a PR → github-expert, never git-expert.

3. Fallback. If no specialist matches, the orchestrator uses worker, which has full tool access.

Two hard rules live in the same file:

• Documentation is delegated, never fetched inline. The orchestrator must not fetch external library or framework docs itself — it spawns docs-fetcher, which tries llms.txt first and extracts only the relevant sections. Skip it when the task is standard-library only, or when the docs were already fetched earlier in the conversation.
• Model overrides are explicit. When you ask for a specific model, the orchestrator calls list_models to discover valid provider/model-id pairs and passes model to subagent. An explicit model argument beats agent_overrides, agent frontmatter, and settings. In parallel task arrays, a per-task model wins over the top-level fallback; chain steps share the top-level model.

A few agents are deliberately not in the chat routing table. The five code-reviewer-* agents and test-runner are dispatched by the review loop in rules/20-code-review-loop.md — all six run in parallel after every code change, and the first review is never skipped. The three issue-reviewer-* agents are dispatched together by the /issue-review prompt template. Use chat routing rules, prompt templates, or slash commands deliberately; see Managing Custom Agents for how the two styles differ.

Language specialists

Full read, write, edit, bash — they implement, not just advise.

Infrastructure and CI

Version control and forges

These two are split deliberately: git-expert is local repository work, github-expert is everything that talks to the GitHub API through gh. conflict-resolver is split out of git-expert because it is the one git task that needs real judgment: git-expert is commonly pinned to a small model, so when a merge, rebase, or cherry-pick leaves unmerged paths, git-expert is blocked from writing a resolution (git add, git restore, git rm, git update-index, git reset, git checkout --ours/--theirs, and the --continue/--skip/--quit flags of merge|rebase|cherry-pick|revert|am) and hands off to conflict-resolver. Reads such as git status and git diff, and the --abort flags, stay allowed.

Both git-expert and github-expert are read-only on the file system, but bash is enough to mutate branches and open PRs. conflict-resolver writes, because resolving a conflict means editing the conflicted files.

Testing

Running tests and writing tests are separate agents. test-runner is analysis-only; a completed test-runner or test-automator subagent does not prove the test command passed — the exit status does.

Documentation

docs-fetcher is the mandatory delegate for external docs. The other two write docs into your project.

Security

Scoped to third-party repositories you are considering adopting, not to auditing your own code — that is code-reviewer-security's job.

Code review

The five code-reviewer-* agents are dispatched by the review loop, not by chat routing. After any code change, all five plus test-runner run in parallel as async subagents, and the loop repeats until the state is clean (capped by review_loop_max_cycles). reviewer is the general-purpose single-agent review.

All six reviewers are read-only. Spec findings are never deduplicated against non-spec findings.

Issue review

Spawned together by /issue-review, all read-only, all returning JSON findings that the template merges and deduplicates.

Orchestration and general work

scout → planner → worker is the chain behind /implement; /scout-and-plan stops after the first two. worker is also the routing-table fallback for anything with no specialist.

planner and debugger deliberately cannot write. worker is the only one in this group that can.

Tool access at a glance

• Full access (read, write, edit, bash) — 13 agents: the five language specialists, docker-expert, kubernetes-expert, jenkins-expert, api-documenter, technical-documentation-writer, test-automator, conflict-resolver, worker.
• Read-only (read, bash) — the other 17: every reviewer, every issue reviewer, git-expert, github-expert, test-runner, debugger, planner, scout, docs-fetcher, security-auditor.

Restricting tools: is the first lever when a bundled specialist has more authority than you want; see Managing Custom Agents.

Related Pages

• Managing Custom Agents
• Built-in Workflow Commands
• Automating Code Reviews
• Running Background Agents and Scheduled Tasks
• Inter-Agent Communication
• Configuration & Settings