Custom Agents

Pochi allows you to define custom agents to handle specific tasks. These agents can be tailored with their own system prompts and sets of tools, enabling you to create specialized assistants for your workflows.

Defining a Custom Agent

Custom agents are defined in .md files located in either the project's .pochi/agents/ directory or the system-wide ~/.pochi/agents/ directory.

An agent definition file consists of two parts: a frontmatter section for configuration and a content section for the system prompt.

Here is an example of a custom agent definition:

---
description: Description of when this custom agent should be invoked
tools:
  - tool-1
  - tool-2
  - tool-3
---

Your custom agent's system prompt goes here. This can be multiple paragraphs
and should clearly define the custom agent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the custom agent should follow.

If the agent is saved as my-agent.md and the name attribute is omitted, my-agent will be used as the agent name.

Configuration

The frontmatter provides metadata for the custom agent:

• name (optional): A unique name for your agent. If omitted, the filename (without the extension) is used as the name.
• description (required): A short description of what the agent does. This is used to help Pochi decide when to use your agent.
• tools (optional): A list of tools that the agent is allowed to use. This can be a comma-separated string (e.g., tool-1, tool-2) or a YAML array. If omitted, the agent inherits all available tools.

Tool-specific rules

Rule entries follow the format tool or tool(specifier). The following tools support specifier-based restrictions:

• executeCommand, startBackgroundJob — Command patterns, e.g. executeCommand(npm run *), startBackgroundJob(npm run dev)
• readFile, writeToFile, applyDiff, editNotebook — Path globs, e.g. readFile(src/**)
• webFetch — Domain patterns, e.g. webFetch(domain:*.example.com)

A tool declared without parentheses (e.g., readFile) has no restrictions. Use one declaration per rule — commas inside a specifier are not supported; add separate entries for multiple rules.

Command Execution Restrictions

Restrict which shell commands the agent can run via executeCommand. The specifier is matched against each individual command segment (split on ;, &&, ||, |). If any segment does not match at least one allowed pattern, the tool call is rejected.

Background Job Restrictions

Restrict which long-running commands the agent can launch via startBackgroundJob. The same command-pattern matching used for executeCommand applies here, but the two policies are independent — an executeCommand(...) rule does not authorize a startBackgroundJob call, and vice versa. Declare separate entries for each tool as needed.

Path-based File Restrictions

Restrict which files the agent can read or modify using workspace-relative glob patterns. Applies to readFile, writeToFile, applyDiff, and editNotebook. Access to any path outside the specified patterns is rejected.

Domain-based Web Restrictions

Restrict which domains the agent can fetch via webFetch. The specifier must start with domain:. URLs whose hostname does not match any allowed pattern are rejected.

New Task Restrictions

Restrict which agent types a custom agent can launch using newTask.

• newTask(_) allows launching only the default agent (when agentType is omitted).
• newTask(browser) allows launching only the browser agent.
• newTask(explorer-*) allows launching any agent whose name starts with explorer-.

Example:

---
description: Code reviewer with restricted filesystem and network access
tools:
  - executeCommand(git diff)
  - executeCommand(grep *)
  - startBackgroundJob(npm run dev)
  - readFile(src/**)
  - readFile(packages/**/*.md)
  - writeToFile(.pochi/**)
  - webFetch(domain:docs.example.com)
  - webFetch(domain:*.getpochi.com)
  - newTask(_)
  - newTask(browser)
---

System Prompt

The content of the file after the frontmatter is the system prompt for the agent. This prompt should define the agent's role, capabilities, and how it should behave.

Using a Custom Agent

You can mention the custom agent's name in your prompt, and Pochi may decide to use it based on the context.

Managing Custom Agents

You can manage your custom agents through the Pochi interface or by directly manipulating the agent definition files. The common operations include:

• List: View all available agents in the .pochi/agents/ directory or in Pochi settings.
• Create: Create a new .md file in the .pochi/agents/ directory.
• Delete: Remove the corresponding agent file.
• Edit: Modify the agent's definition file.