Agent Definitions

Agent definitions are markdown files that define specialized agents with scoped tools, custom instructions, and optional model overrides. They’re used by the subagent tool and spawn_session to create focused child agents — letting you delegate work to purpose-built agents instead of one monolithic session.

---

File Format

Each agent definition is a markdown file with YAML frontmatter:

---
name: researcher
description: Read-only codebase research and analysis
tools: read,grep,find,ls
model: sonnet
---

You are a research agent. Read files, trace dependencies,
and summarize findings without modifying anything.

Frontmatter Fields

Field	Type	Required	Description
name	string	✅	Identifier used to invoke the agent
description	string	✅	Tells the parent agent when to use this agent; also used for skill matching
tools	string	—	Comma-separated list of allowed tool names. Omit to inherit the default coding toolset.
disallowedTools	string	—	Comma-separated tools to remove from the inherited or specified toolset.
model	string	—	Model override. Accepts a bare ID (claude-haiku-4-5), provider/id form (anthropic/claude-haiku-4-5), or aliases haiku, sonnet, opus. inherit or omit to auto-select the cheapest available model.
maxTurns	number	—	Maximum agentic turns before the subagent stops.
permissionMode	string	—	Permission mode: default, acceptEdits, dontAsk, bypassPermissions, plan. plan restricts to read-only tools.
background	boolean	—	Hint that this agent should run as a background task.

The body text (everything after the frontmatter) becomes the agent’s system prompt.

---

Discovery Paths

PizzaPi searches for agent definitions in these directories:

Path	Scope
~/.pizzapi/agents/	Global — available in all projects
~/.claude/agents/	Global — Claude Code compatibility
<cwd>/.pizzapi/agents/	Project-local — scoped to this repo (walk-up search from cwd)
<cwd>/.claude/agents/	Project-local — Claude Code compatibility (walk-up search from cwd)

Within each scope, .pizzapi/agents/ takes precedence over .claude/agents/. Project agents override user agents of the same name, and built-in agents are lowest priority.

• Directory~/.pizzapi/

  • Directoryagents/

    • researcher.md
    • reviewer.md
• Directorymy-project/

  • Directory.pizzapi/

    • Directoryagents/

      • refactorer.md
  • Directory.claude/

    • Directoryagents/

      • legacy-agent.md
  • Directorysrc/

    • …
  • package.json

The agentScope parameter in the subagent tool controls which directories are searched:

• "user" (default) — only global dirs (~/.pizzapi/agents/, ~/.claude/agents/)
• "project" — only project-local dirs (.pizzapi/agents/, .claude/agents/)
• "both" — all directories

When agentScope is "project" or "both", project agents require confirmation. If no UI is available (headless/runner contexts), the call fails closed with a refusal. Set confirmProjectAgents: false in the subagent tool parameters to allow project agents in headless mode.

---

Tool Restrictions

The tools: frontmatter limits what tools the agent can access:

• Comma-separated tool names: read,grep,find,ls
• Omitting tools: gives the agent the default coding toolset: bash, read, write, edit, grep, find, ls
• MCP/extension tools are not selectable for subagents
• Built-in tool names: bash, read, write, edit, grep, find, ls

Restrict tools for safety

A reviewer agent shouldn’t have write access — limit it to read,grep,find so it can analyze code without accidentally modifying anything. The same principle applies to research agents, auditors, or any agent whose job is to observe and report.

---

Using Agent Definitions

Agent definitions are invoked through the subagent tool:

{
  "agent": "researcher",
  "task": "Find all API endpoints in this codebase"
}

See Subagents for full documentation.

spawn_session

spawn_session is a separate tool for launching independent linked child sessions. It takes an inline prompt and does not load agent definition files:

{
  "prompt": "Review all TypeScript files for security issues"
}

See CLI Reference for details.

---

Built-in task Agent

A general-purpose task agent is always available without any definition file. Use it for ad-hoc delegation when you don’t need scoped tools or a custom system prompt:

{
  "agent": "task",
  "task": "Refactor the auth module to use async/await"
}

---

Examples

researcher.md

A read-only research agent that can explore but never modify.

---
name: researcher
description: Read-only codebase research and analysis — traces dependencies, summarizes architecture, and answers questions about the code.
tools: read,grep,find,ls
model: sonnet
---

You are a research agent. Your job is to read files, trace dependencies,
and summarize findings. You MUST NOT modify any files.

When given a task:
1. Search the codebase to find relevant files
2. Read and understand the code
3. Provide a clear, structured summary of your findings
4. Include file paths and line numbers for all references

refactorer.md

A code transformation agent with read and write access.

---
name: refactorer
description: Targeted code refactoring — makes precise changes to improve code quality while preserving behavior.
tools: read,write,edit,bash
---

You are a refactoring agent. Make targeted code transformations that
improve quality while preserving existing behavior.

Rules:
1. Read and understand the code before making changes
2. Make the smallest change that achieves the goal
3. Run existing tests after every change (`bun test`)
4. If tests fail, revert and try a different approach
5. Never change public API signatures without explicit approval

reviewer.md

A code review agent with no write access.

---
name: reviewer
description: Code review agent — finds bugs, security issues, and style problems. Suggests improvements without modifying files.
tools: read,grep,find
---

You are a code review agent. Analyze code for bugs, security
vulnerabilities, and improvement opportunities.

For each issue found, report:
- **File** and **line number**
- **Severity**: critical / warning / suggestion
- **Description** of the problem
- **Suggested fix** (as a code snippet, but do NOT apply it)

Prioritize security issues and correctness bugs over style nits.

---

Managing Agent Definitions via the API

PizzaPi provides a full CRUD API for managing agent definitions on a connected runner. You can create, edit, and delete agents from the web UI without manually editing files on disk.

API Endpoints

All endpoints require an authenticated session and are scoped to a specific runner.

Method	Endpoint	Description
GET	/api/runners/{runnerId}/agents	List all discovered agent definitions (from Redis cache)
GET	/api/runners/{runnerId}/agents/{name}	Get full content of a specific agent definition
POST	/api/runners/{runnerId}/agents	Create a new agent (body: { name, content })
PUT	/api/runners/{runnerId}/agents/{name}	Update an existing agent (body: { content })
DELETE	/api/runners/{runnerId}/agents/{name}	Delete an agent definition
POST	/api/runners/{runnerId}/agents/refresh	Re-scan the filesystem and refresh the agent list

Using the Web UI

In the PizzaPi web interface, navigate to a runner’s detail page and open the Agents tab. From there you can:

• Browse all agent definitions discovered from the runner’s agent directories
• Create a new agent definition with the in-browser editor (including frontmatter for name, description, tools, model, etc.)
• Edit an existing agent’s content and configuration
• Delete agent definitions you no longer need
• Refresh to re-scan the filesystem if you’ve added definitions outside the UI

Relationship to File-Based Discovery

The API writes directly to the same directories used by file-based discovery (~/.pizzapi/agents/, ~/.claude/agents/, etc.). An agent created via the API is a regular .md file on disk — there’s no separate “API-only” storage. Similarly, agents added to the filesystem can be picked up by hitting the Refresh button or calling the /refresh endpoint.

Note

Agent names are validated to prevent path traversal — alphanumeric characters, hyphens, underscores, and dot-separated segments; maximum 64 characters.