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.

---

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:

	pi-agent-mode	pi-subagents	pi-open-agents
Primary agent switching	✅	❌	✅
Subagent delegation	❌	✅	✅
Per-agent thinking level	❌	❌	✅
Permission system	❌	❌	✅
OpenCode .agent.md format	❌	❌	✅

---

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.

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>" })

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-*)

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

mode	TUI selector	subagent tool	set_agent tool
primary	✅ visible	❌	✅
subagent	❌	✅ available	✅
all (default)	✅ visible	✅ available	✅

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.):

Mode	System prompt	Context files
append (default)	pi's prompt + agent body	✅ loaded
replace	Agent body only	✅ loaded
replace-all	Agent body only	❌ disabled

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):

Path	Scope	Format
~/.pi/agent/agents/*.md	Global	pi
~/.opencode/{agent,agents,mode}/*.md	Global	OpenCode
.pi/agents/*.md	Project	pi
.opencode/{agent,agents,mode}/*.md	Project	OpenCode
.agents/*.md	Project	Shared

---

Usage

Interactive

Action	What it does
/agent	Open agent selector (primary/all only)
/agent <name>	Switch to agent directly
/agents	List all agents
/agent-search <query>	Search agents
Ctrl+Shift+M	Cycle agents
--agent <name>	CLI flag for startup agent

Programmatic (LLM tools)

Tool	Description
set_agent	Switch agent programmatically
search_agents	Search agents by name/description/body
subagent	Delegate task to a subagent (subagent/all mode only)

---

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

---

Development

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

npm install
npm test          # 117 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