pi-open-agents

Unified agent and subagent management for pi, with OpenCode-compatible agent definitions.

Replaces pi-agent-mode + @johnnywu/pi-subagents with one coherent plugin.

Why pi? Pi's minimalist core keeps system prompts under 1,000 tokens — making it exceptionally fast on local models and cheap on cloud APIs. pi-open-agents is built to leverage that minimalism. See Pi vs OpenCode: Performance & Architecture for a detailed comparison.

🐑 Herd your agents. pi-open-agents + Herdr runs a full team of coding agents — persistent workspaces, live agent awareness, control from one screen. Set up the stack in 5 commands →

Quick start

pi install npm:pi-open-agents

Remove old plugins from ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-open-agents"]
}

Existing .agent.md files work without changes (default mode: all).

Agents vs subagents (and why you need both)

People tend to lump "agents" and "subagents" together. They're not the same thing, and the difference is the whole game.

An agent changes your session. Switch to one and the conversation you're already having starts thinking with a different brain — different prompt, different model, different tools, different rules. The thread keeps going; what's running it changes. Planning wants a slow, deliberate mind. Coding wants a fast one. Reviewing wants a skeptic. An agent is how you become the right one for the moment.

A subagent never touches your session. It's a separate process you spin up for one job — usually on a cheaper, faster model, with locked-down permissions — that works in isolation and hands you back an answer. Your context stays clean; your main model keeps its focus.

The payoff is using both. You sit in an orchestrator agent — the strong model holding the plan — and delegate the grunt work to subagents: search these five hundred files, run that test matrix, draft the boilerplate. One mind to think, many hands to do. You get the big model's reasoning and the small models' speed and economy, without one poisoning the other's context.

And the moment you delegate, control stops being optional. A subagent is a real process with real tools — it can read your secrets, rewrite your files, run shell. So you choose its model, set its thinking level, clip its permissions to read-only or git-only, cap how deep it can recurse, decide who's even allowed to spawn whom. That's not red tape. It's what turns delegate and pray into delegate and trust — and it's exactly what this plugin gives you.

Why this exists

Pi splits agent management across two separate plugins — one for primary agents, one for subagents. They use incompatible schemas, conflict on model routing, and have no permission system. pi-open-agents replaces both:

Popular requests, already covered

Some of the most upvoted agent/subagent asks across the ecosystem are already here — or native in pi itself:

Features

Per-agent model, thinking, and permissions

Every agent defines its own model:, thinking:, and permission: — no global overrides, no sentinel values, no workarounds. An orchestrator can run on a strong reasoning model while subagents run on a fast local model:

---
name: orchestrator
mode: primary
model: anthropic/claude-sonnet
thinking: high
---

---
name: fast-worker
mode: subagent
model: lm-studio/qwen-2.5-coder
thinking: off
---

Permission system

Go beyond a simple tool whitelist. OpenCode-style rules with glob patterns, deny rules, and per-action restrictions:

permission:
  "*": allow              # default: everything allowed
  "edit": deny            # read-only agent
  "bash":
    "git *": allow        # only git commands
    "rm *": deny          # never delete
  "subagent": deny        # no delegation

Tool names are normalized automatically: task → subagent, vscode → read, apply_patch → edit (OpenCode-only tool). In pi, write and edit are separate tools — write creates/overwrites files, edit does search-and- replace — so they have separate permission categories.

Runtime enforcement (v0.1.24). Every tool call is evaluated against the active agent's rules before it runs — not just used to filter the toolset:

• deny blocks the call; the model receives a clear denial reason
• ask opens a dialog: Allow once / Allow always (this session) / Deny
• Patterns are argument-aware: file paths for read/edit/write, command strings for bash ("rm -rf *": deny, "**/*.env": deny — * doesn't cross /, use ** for nested paths)
• Rules are evaluated top-to-bottom, last match wins — put specific rules after catch-alls ("*": ask first, then "git *": allow)
• A call matching no pattern within a configured category proceeds (rule lists are deny/ask lists, not exhaustive allowlists)

⚠️ Migration note (v0.1.24): ask is now enforced — previously it was parsed but silently ignored. In non-interactive processes (subagent children, print/JSON mode) an ask rule blocks the call (fail-closed): add an explicit allow rule if a subagent needs that tool. deny now also blocks matching individual calls (patterns included), not just statically hiding whole tools. (#20)

Inheritance down the delegation chain (#8). A subagent can never exceed the authority of the agent that delegated to it — in both directions of the rule language:

• Tool ceiling: at delegation the parent's live tool set is snapshotted (pi.getActiveTools()), minus tools it blanket-denys or blanket-asks (ask is not authority: headless children have no approval bridge). The child's own whitelist is intersected with that ceiling and passed via --tools — an empty intersection becomes --no-tools, never "all tools".
• Argument patterns: the parent's deny/ask rules (patterns included) travel to the child's gate and are evaluated last, so the child cannot widen them (write: {"**/*.env": deny} upstream blocks .env writes two levels deep, whatever the child declares).
• Transitive: the ceiling the child launches with is the child's active set — a grandchild cannot regain any tool removed at an earlier hop.

Iterating on agents: /reload

Edit a .agent.md file (or add/remove one) and run pi's built-in /reload — no session restart (#9). Agent definitions are re-discovered, the active agent is kept (your mid-session switch survives; --agent is a startup-only default), and a deleted/disabled active agent falls back cleanly with a warning. New agents appear in /agents and the subagent tool list immediately.

Auto-injected delegation guidance

If an agent has the subagent tool, the plugin automatically appends a ## Subagent Delegation block to its system prompt — listing available subagents and the correct call syntax:

subagent({ agent: "<name>", task: "<task>", cwd?, session?, model? })

You never need to explain delegation mechanics in agent prompts. The plugin handles it, the same way pi handles tool descriptions.

Subagent execution engine

When an agent delegates, the plugin spawns a child pi process with the target agent's configuration. The child runs in isolation — it gets --model, --system-prompt, and --tools from the executor, not from settings.json. This means:

• The primary agent's defaultAgent never leaks into subagents
• Each subagent runs with exactly the model and tools it declares
• Skills load per-agent, with wildcard support (security-*, git-*)

skills: is subagent-only (#19). pi discovers skills once at session startup and exposes no per-agent filter, so a primary cannot role-scope them. Declaring skills: on a primary (or all) agent warns on apply and the field is ignored; the subagent child receives exactly its listed skills, injected into its system prompt.

Per-call model override: the caller can override the agent's default for a single call — subagent({ agent: "deep-research", task: "...", model: "zai/glm-5.3-flash" }). Handy for "run this one task on the cheap model" without forking an agent definition. Malformed values (no-slash) are rejected before any spawn. Aggregator providers work too — the model id may contain slashes: model: "openrouter/anthropic/claude-opus-5.5".

The --tools whitelist is derived from both explicit tools: arrays and permission allow-lists. An agent with permission: { read: allow, edit: allow } will only get read and edit in the child process. Wildcard permissions (*: allow) cannot produce a finite whitelist — the child gets all tools.

OpenCode compatibility

Your .opencode/agent/ files work as-is. The tools map format is auto-converted to permission rules, and pi-specific fields (thinking, maxDepth, allowedAgents) are simply ignored by OpenCode without breaking:

# OpenCode format — works in pi without changes
name: triage
mode: subagent
tools:
  read: true
  bash: false

The tools map is converted to permission rules and also restricts the subagent child process — a subagent with tools: { read: true, bash: false } will only have access to the read tool when spawned.

Mode-based visibility

Use primary for user-facing agents, subagent for delegated workers, all when an agent serves both roles.

Agent definition format

---
name: my-agent                          # required
description: One-line description
mode: subagent                          # primary | subagent | all (default: all)
hidden: false                           # hide from TUI selectors
color: "#44BA81"

model: anthropic/claude-sonnet          # per-agent model override
thinking: xhigh                         # off|minimal|low|medium|high|xhigh
systemPrompt: replace                   # append | replace | replace-all (default: append)

permission:
  "*": allow
  "question": deny
  "edit":
    "*.env": deny

maxDepth: 5                             # subagent recursion limit
allowedAgents: [explorer]               # restrict which subagents this can spawn
skills: security-audit, git-*           # per-agent skills with wildcards
---
Your prompt goes here. This becomes the agent's system prompt.

System prompt modes

The systemPrompt field controls how the agent body interacts with pi's default prompt and workspace context files (CLAUDE.md, etc.):

Use replace-all for fully isolated agents that should not be influenced by workspace context — e.g., a subagent that must run identically regardless of the project it's invoked from.

For subagents (child process), the agent body is the system prompt — pi's default prompt is not included. Skills are injected as an XML block after the body.

Discovery paths

Agents are loaded from multiple locations (project overrides global by name):

⚠️ Migration note (v0.1.22): discovery in the shared .agents/ directory is now scoped to ​.agents/agents/*.md — previously every markdown file under .agents/ (including skills/ and commands/) was parsed as an agent and showed up in /agents and the subagent tool. If you relied on the loose loading, move your agent files into .agents/agents/. Skills and commands are picked up natively by pi as before. (#14)

Usage

Interactive

Programmatic (LLM tools)

Migration

pi install npm:pi-open-agents

Remove npm:pi-agent-mode and npm:@johnnywu/pi-subagents from settings.json. Existing agent .md files work without changes.

Optional cleanup:

1. Add mode: primary or mode: subagent to agent files for explicit visibility
2. Gradually adopt permission: over the old tools: whitelist

Run a fleet 🐑

Pi stays minimal on purpose — one agent, done well. When you need many, add Herdr: persistent workspaces, mouse-first UX, live agent awareness (idle / working / blocked), and cross-agent control from one screen — pi, or any mix of the 25 supported agent kinds. Six agents, six sessions, zero chaos: that's the exact workstation setup documented in pi × Herdr × pi-open-agents.

Roadmap

• Parent permission inheritance for subagents — ✅ shipped in 0.1.27 (#8)
• Agent hot-reload — ✅ works via pi's built-in /reload, shipped in 0.1.27 (#9)
• Per-call model override in subagent() — ✅ shipped in 0.1.19 (#10)
• Parallel subagent limit — #11

Development

Contributing? Please read the Contributing Guide before opening an issue or pull request.

npm install
npm test          # 178 tests
npm run typecheck # tsc --noEmit

Docker testing

docker compose run --rm pi-sandbox

See ARCHITECTURE.md for the full technical design.

Attribution

This project builds on code and ideas from:

• pi-agent-mode by ZGltYQ (MIT)
• pi-subagents by jwu (MIT)
• opencode by sst (MIT)

See ATTRIBUTION.md for details.

License

MIT