# @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](https://github.com/sdougbrown/avenor) as pi subprocesses: `avenor_spawn(agent: "reviewer", backend: "pi")`

## Install

```bash
# 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):

```json
{
  "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`:

```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.

## 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

```bash
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:

```text
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](https://github.com/sdougbrown/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