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

---

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