@dougbots/pi-agents

Agent profiles for pi — preconfigured model, system prompt, tool restrictions, and permission gates.

What it does

Defines named agent profiles (mirroring opencode's agent concept) that can be:

• Activated on the current session: /agent jockey
• Booted at startup: PI_AGENT=reviewer pi
• Spawned by avenor as pi subprocesses: avenor_spawn(agent: "reviewer", backend: "pi")

Install

# As a pi package (recommended)
pi install git:github.com/sdougbrown/pi-agents

# Local development
pi install /path/to/pi-agents

Config

~/.pi/agent/agents.json (global) and .pi/agents.json (project, overrides global):

{
  "reviewer": {
    "description": "Code reviewer — no edits",
    "model": "provider/model-id",
    "systemPrompt": "inline text or file:/path/to/prompt.md",
    "thinkingLevel": "high",
    "excludeTools": ["write", "edit"],
    "permissions": {
      "bash": {
        "allow": ["git *", "npm test *"],
        "deny": ["git push*", "rm -rf*"]
      }
    }
  }
}

Profile fields:

• model — "provider/model-id" (required)
• systemPrompt — inline string or file:/absolute/path (required)
• thinkingLevel — off | low | medium | high | xhigh
• tools — allowlist of tool names (if set, only these are callable)
• excludeTools — denylist of tool names (removed from available set)
• permissions.bash — { allow?: string[], deny?: string[] } with glob patterns

Runtime agent profiles

A runtime agent profile is a session-scoped overlay for role profiles. It can change execution settings without changing the role's system prompt, tools, or permission boundary. Define global profiles in ~/.pi/agent/agent-profiles.json and project overrides in .pi/agent-profiles.json:

{
  "cloud": {
    "description": "Temporary cloud fallbacks",
    "agents": {
      "explore": { "model": "sparky/deepseek-flash" },
      "mule": { "model": "sparky/deepseek-flash" },
      "reviewer": { "model": "sparky/deepseek-flash" }
    }
  }
}

Only model and thinkingLevel may be overridden. Project profile entries merge over global entries by profile and agent name. Malformed entries are ignored and reported as a Pi warning. A selected profile is persisted in the Pi session and restored by /resume.

PI_AGENT_PROFILE=<name> is an explicit launch-time override; PROFILE=<name> is accepted as a convenience alias. Both take precedence over a saved session selection. Explicit --model still takes precedence over an agent-profile's model.

While a session has a profile active, the extension reflects it into process.env.PI_AGENT_PROFILE (cleared on /agent-profile none). Child processes inherit it, so tooling like agent-model.sh <role> pi resolves the same model the session runs, and fresh dispatches from the session stay on the active profile.

Commands

| Command | Description | |---------|-------------| | /agent <name> | Switch current session to agent profile | | /agent none | Deactivate agent, restore all tools | | /agent | List available agents | | /agents | Same as /agent | | /agent-profile <name> | Select a session-scoped runtime agent profile | | /agent-profile none | Clear the session runtime agent profile | | /agent-profile | Show the active and available runtime agent profiles |

Boot with agent

PI_AGENT=reviewer pi
PI_AGENT=jockey pi -c
PI_AGENT=explore PI_AGENT_PROFILE=cloud pi

Avenor integration

When avenor_spawn(agent: "reviewer", backend: "pi") is called, avenor spawns pi --mode rpc with PI_AGENT=reviewer. The agents extension applies the full profile (model, systemPrompt, tools, permissions) automatically.

Pass model as well to override only the profile's default model while retaining its prompt, tools, and permissions:

avenor_spawn(
  agent: "reviewer",
  model: "anthropic/claude-opus-4",
  backend: "pi",
  prompt: "Review the outage recovery changes",
)

Explicit --model selection takes precedence over the profile default. Avenor forwards its model option to the pi subprocess as --model, so no agent config changes are needed for a one-off override.

Requires avenor with the pi backend (v0.3.3+). Model resolution falls back to ~/.pi/agent/agents.json when the agent is not found in opencode config.

Profile vs. agent

pi-profiles (by Carter McAlister) is a session config overlay — it swaps settings/extensions/skills and reloads the current session. Agents are discrete "personalities" with their own model, prompt, tool restrictions, and permission gates, designed to be spawned as subprocesses by avenor.

Dependencies

• pi — the extension runtime
• avenor — for subprocess spawning with backend: "pi" (optional, for sub-agent workflows)
  • best used with @dougbots/avenor-pi to provide the tools to spawn those processes