pi-open-agents 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +149 -155
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,187 +1,198 @@
|
|
|
1
1
|
# pi-open-agents
|
|
2
2
|
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="./pi-open-agents-banner.png" alt="pi-open-agents" width="640">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
3
7
|
[](https://www.npmjs.com/package/pi-open-agents)
|
|
4
8
|
[](https://opensource.org/licenses/MIT)
|
|
5
9
|
[](https://pi.dev)
|
|
6
10
|
|
|
7
11
|
Unified agent and subagent management for [pi](https://pi.dev), with [OpenCode](https://github.com/sst/opencode)-compatible agent definitions.
|
|
8
12
|
|
|
9
|
-
Replaces `pi-agent-mode`
|
|
13
|
+
Replaces `pi-agent-mode` + `@johnnywu/pi-subagents` with one coherent plugin.
|
|
14
|
+
|
|
15
|
+
> **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](./PI-VS-OPencode.md) for a detailed comparison.
|
|
10
16
|
|
|
11
17
|
---
|
|
12
18
|
|
|
13
|
-
##
|
|
19
|
+
## Quick start
|
|
14
20
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
definitions — so your agents work in **both** pi and OpenCode without modification.
|
|
21
|
+
```bash
|
|
22
|
+
pi install pi-open-agents
|
|
23
|
+
```
|
|
19
24
|
|
|
20
|
-
|
|
25
|
+
Remove old plugins from `~/.pi/agent/settings.json`:
|
|
21
26
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
| OpenCode permission system | ❌ | ❌ | ✅ |
|
|
28
|
-
| OpenCode `.agent.md` format | ❌ | ❌ | ✅ |
|
|
29
|
-
| One plugin for everything | ❌ | ❌ | ✅ |
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"packages": ["npm:pi-open-agents"]
|
|
30
|
+
}
|
|
31
|
+
```
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
Existing `.agent.md` files work without changes (default `mode: all`).
|
|
32
34
|
|
|
33
|
-
|
|
34
|
-
`pi-agent-mode` (primary agents) and `@johnnywu/pi-subagents` (subagent delegation).
|
|
35
|
-
Using them together causes several problems that are **impossible to fix without
|
|
36
|
-
a unified plugin**:
|
|
35
|
+
---
|
|
37
36
|
|
|
38
|
-
|
|
37
|
+
## Why this exists
|
|
39
38
|
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
Pi splits agent management across two separate plugins — one for primary agents,
|
|
40
|
+
one for subagents. They use incompatible schemas, conflict on model routing, and
|
|
41
|
+
have no permission system. `pi-open-agents` replaces both:
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
|
|
43
|
+
| | `pi-agent-mode` | `pi-subagents` | `pi-open-agents` |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| Primary agent switching | ✅ | ❌ | ✅ |
|
|
46
|
+
| Subagent delegation | ❌ | ✅ | ✅ |
|
|
47
|
+
| Per-agent thinking level | ❌ | ❌ | ✅ |
|
|
48
|
+
| Permission system | ❌ | ❌ | ✅ |
|
|
49
|
+
| OpenCode `.agent.md` format | ❌ | ❌ | ✅ |
|
|
45
50
|
|
|
46
|
-
|
|
47
|
-
agent's model. Workarounds like `defaultModel: "_none_"` or removing
|
|
48
|
-
`defaultAgent` entirely become necessary.
|
|
51
|
+
---
|
|
49
52
|
|
|
50
|
-
|
|
51
|
-
independently. No global model override.
|
|
53
|
+
## Features
|
|
52
54
|
|
|
53
|
-
###
|
|
55
|
+
### Per-agent model, thinking, and permissions
|
|
54
56
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
57
|
+
Every agent defines its own `model:`, `thinking:`, and `permission:` — no global
|
|
58
|
+
overrides, no sentinel values, no workarounds. An orchestrator can run on a strong
|
|
59
|
+
reasoning model while subagents run on a fast local model:
|
|
58
60
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
61
|
+
```yaml
|
|
62
|
+
---
|
|
63
|
+
name: orchestrator
|
|
64
|
+
mode: primary
|
|
65
|
+
model: anthropic/claude-sonnet
|
|
66
|
+
thinking: high
|
|
67
|
+
---
|
|
68
|
+
```
|
|
62
69
|
|
|
63
|
-
|
|
70
|
+
```yaml
|
|
71
|
+
---
|
|
72
|
+
name: fast-worker
|
|
73
|
+
mode: subagent
|
|
74
|
+
model: lm-studio/qwen-2.5-coder
|
|
75
|
+
thinking: off
|
|
76
|
+
---
|
|
77
|
+
```
|
|
64
78
|
|
|
65
|
-
|
|
66
|
-
and both ignore fields they don't recognize:
|
|
79
|
+
### Permission system
|
|
67
80
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
| Thinking level | `reasoningEffort` *(ignored)* | Not supported | `thinking` |
|
|
71
|
-
| Tool restrictions | `tools` (CSV) | `tools` (CSV) | `permission` (rules) + `tools` (CSV) |
|
|
72
|
-
| Agent visibility | `mode` *(ignored)* | Not supported | `mode: primary\|subagent\|all` |
|
|
73
|
-
| Prompt injection | Not configurable | `systemPrompt` | `systemPrompt: append\|replace\|replace-all` |
|
|
74
|
-
| Model override | Global (all agents) | Per-agent | Per-agent |
|
|
81
|
+
Go beyond a simple tool whitelist. OpenCode-style rules with glob patterns, deny
|
|
82
|
+
rules, and per-action restrictions:
|
|
75
83
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
84
|
+
```yaml
|
|
85
|
+
permission:
|
|
86
|
+
"*": allow # default: everything allowed
|
|
87
|
+
"edit": deny # read-only agent
|
|
88
|
+
"bash":
|
|
89
|
+
"git *": allow # only git commands
|
|
90
|
+
"rm *": deny # never delete
|
|
91
|
+
"subagent": deny # no delegation
|
|
92
|
+
```
|
|
79
93
|
|
|
80
|
-
|
|
94
|
+
Tool names are normalized automatically: `write` → `edit`, `task` → `subagent`,
|
|
95
|
+
`vscode` → `read`.
|
|
81
96
|
|
|
82
|
-
|
|
83
|
-
limited to a simple CSV whitelist (`tools: bash, read`) with no pattern matching,
|
|
84
|
-
no deny rules, and no per-file restrictions.
|
|
97
|
+
### Auto-injected delegation guidance
|
|
85
98
|
|
|
86
|
-
|
|
87
|
-
`
|
|
88
|
-
|
|
99
|
+
If an agent has the `subagent` tool, the plugin automatically appends a
|
|
100
|
+
`## Subagent Delegation` block to its system prompt — listing available
|
|
101
|
+
subagents and the correct call syntax:
|
|
89
102
|
|
|
90
|
-
|
|
103
|
+
```
|
|
104
|
+
subagent({ agent: "<name>", task: "<task>" })
|
|
105
|
+
```
|
|
91
106
|
|
|
92
|
-
|
|
93
|
-
|
|
107
|
+
You never need to explain delegation mechanics in agent prompts. The plugin
|
|
108
|
+
handles it, the same way pi handles tool descriptions.
|
|
94
109
|
|
|
95
|
-
|
|
96
|
-
- Setting `defaultModel` to a sentinel value (`"_none_"`) to prevent global override
|
|
97
|
-
- Using context-based model IDs to force provider isolation
|
|
98
|
-
- Multiple rapid commits to diagnose model routing failures
|
|
110
|
+
### Subagent execution engine
|
|
99
111
|
|
|
100
|
-
|
|
112
|
+
When an agent delegates, the plugin spawns a child pi process with the target
|
|
113
|
+
agent's configuration. The child runs in isolation — it gets `--model`,
|
|
114
|
+
`--system-prompt`, and `--tools` from the executor, not from `settings.json`.
|
|
115
|
+
This means:
|
|
101
116
|
|
|
102
|
-
|
|
117
|
+
- The primary agent's `defaultAgent` never leaks into subagents
|
|
118
|
+
- Each subagent runs with exactly the model and tools it declares
|
|
119
|
+
- Skills load per-agent, with wildcard support (`security-*`, `git-*`)
|
|
103
120
|
|
|
104
|
-
|
|
105
|
-
- **OpenCode users** who want to try pi without rewriting their agent definitions
|
|
106
|
-
- **Teams** who want a portable, version-controlled agent library that works across harnesses
|
|
107
|
-
- **Anyone** who wants per-agent thinking levels, permission rules, or model overrides in pi
|
|
121
|
+
### OpenCode compatibility
|
|
108
122
|
|
|
109
|
-
|
|
123
|
+
Your `.opencode/agent/` files work as-is. The `tools` map format is auto-converted
|
|
124
|
+
to permission rules, and pi-specific fields (`thinking`, `maxDepth`, `allowedAgents`)
|
|
125
|
+
are simply ignored by OpenCode without breaking:
|
|
110
126
|
|
|
111
|
-
```
|
|
112
|
-
pi
|
|
127
|
+
```yaml
|
|
128
|
+
# OpenCode format — works in pi without changes
|
|
129
|
+
name: triage
|
|
130
|
+
mode: subagent
|
|
131
|
+
tools:
|
|
132
|
+
read: true
|
|
133
|
+
bash: false
|
|
113
134
|
```
|
|
114
135
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
```json
|
|
118
|
-
{
|
|
119
|
-
"packages": [
|
|
120
|
-
"npm:pi-open-agents"
|
|
121
|
-
]
|
|
122
|
-
}
|
|
123
|
-
```
|
|
136
|
+
### Mode-based visibility
|
|
124
137
|
|
|
125
|
-
|
|
138
|
+
| `mode` | TUI selector | `subagent` tool | `set_agent` tool |
|
|
139
|
+
|--------|-------------|-----------------|------------------|
|
|
140
|
+
| `primary` | ✅ visible | ❌ | ✅ |
|
|
141
|
+
| `subagent` | ❌ | ✅ available | ✅ |
|
|
142
|
+
| `all` (default) | ✅ visible | ✅ available | ✅ |
|
|
126
143
|
|
|
127
|
-
|
|
144
|
+
Use `primary` for user-facing agents, `subagent` for delegated workers, `all` when
|
|
145
|
+
an agent serves both roles.
|
|
128
146
|
|
|
129
|
-
|
|
130
|
-
- **Mode-based visibility** — `primary` in the TUI selector, `subagent` for delegation, `all` for both
|
|
131
|
-
- **OpenCode-compatible** — reads agents from `.opencode/agent/`, `.opencode/mode/`, and `.agents/`
|
|
132
|
-
- **Permission system** — OpenCode-style `allow`/`deny`/`ask` with glob patterns, last-match-wins
|
|
133
|
-
- **Thinking level per-agent** — `off`/`minimal`/`low`/`medium`/`high`/`xhigh`, with fallback to `settings.json`
|
|
134
|
-
- **Subagent execution** — child pi process spawning with scoped tools, skills, and session fork
|
|
135
|
-
- **Skill loading** — per-agent skills with wildcard support (`lark-*`, `github`)
|
|
147
|
+
---
|
|
136
148
|
|
|
137
149
|
## Agent definition format
|
|
138
150
|
|
|
139
151
|
```yaml
|
|
140
152
|
---
|
|
141
|
-
#
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
hidden: false # hide from TUI selectors
|
|
153
|
+
name: my-agent # required
|
|
154
|
+
description: One-line description
|
|
155
|
+
mode: subagent # primary | subagent | all (default: all)
|
|
156
|
+
hidden: false # hide from TUI selectors
|
|
146
157
|
color: "#44BA81"
|
|
147
158
|
|
|
148
|
-
#
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
# === Execution ===
|
|
152
|
-
thinking: xhigh # off|minimal|low|medium|high|xhigh
|
|
153
|
-
systemPrompt: append # append | replace | replace-all (default: append)
|
|
159
|
+
model: anthropic/claude-sonnet # per-agent model override
|
|
160
|
+
thinking: xhigh # off|minimal|low|medium|high|xhigh
|
|
161
|
+
systemPrompt: replace # append | replace | replace-all (default: append)
|
|
154
162
|
|
|
155
|
-
# === Permissions (OpenCode-style) ===
|
|
156
163
|
permission:
|
|
157
164
|
"*": allow
|
|
158
|
-
"
|
|
159
|
-
"
|
|
160
|
-
"
|
|
165
|
+
"question": deny
|
|
166
|
+
"edit":
|
|
167
|
+
"*.env": deny
|
|
161
168
|
|
|
162
|
-
#
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
skills: security-audit, git-* # per-agent skills with wildcards
|
|
169
|
+
maxDepth: 5 # subagent recursion limit
|
|
170
|
+
allowedAgents: [explorer] # restrict which subagents this can spawn
|
|
171
|
+
skills: security-audit, git-* # per-agent skills with wildcards
|
|
166
172
|
---
|
|
167
|
-
|
|
168
|
-
and maintainability issues. Never modify files — report findings only.
|
|
173
|
+
Your prompt goes here. This becomes the agent's system prompt.
|
|
169
174
|
```
|
|
170
175
|
|
|
171
|
-
###
|
|
176
|
+
### System prompt modes
|
|
177
|
+
|
|
178
|
+
The `systemPrompt` field controls how the agent body interacts with pi's default
|
|
179
|
+
prompt and workspace context files (CLAUDE.md, etc.):
|
|
172
180
|
|
|
173
|
-
|
|
174
|
-
|
|
181
|
+
| Mode | System prompt | Context files |
|
|
182
|
+
|------|---------------|---------------|
|
|
183
|
+
| `append` (default) | pi's prompt + agent body | ✅ loaded |
|
|
184
|
+
| `replace` | Agent body only | ✅ loaded |
|
|
185
|
+
| `replace-all` | Agent body only | ❌ disabled |
|
|
175
186
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
| `replace` | Agent body replaces pi's prompt (primary agents: same as `append` in inline mode) |
|
|
180
|
-
| `replace-all` | Only the agent body is used — pi's prompt is discarded entirely |
|
|
187
|
+
Use `replace-all` for fully isolated agents that should not be influenced by
|
|
188
|
+
workspace context — e.g., a subagent that must run identically regardless of
|
|
189
|
+
the project it's invoked from.
|
|
181
190
|
|
|
182
|
-
For **subagents** (child process), the agent body **is** the system prompt —
|
|
183
|
-
prompt is not included.
|
|
184
|
-
|
|
191
|
+
For **subagents** (child process), the agent body **is** the system prompt —
|
|
192
|
+
pi's default prompt is not included. Skills are injected as an XML block after
|
|
193
|
+
the body.
|
|
194
|
+
|
|
195
|
+
---
|
|
185
196
|
|
|
186
197
|
## Discovery paths
|
|
187
198
|
|
|
@@ -195,13 +206,7 @@ Agents are loaded from multiple locations (project overrides global by name):
|
|
|
195
206
|
| `.opencode/{agent,agents,mode}/*.md` | Project | OpenCode |
|
|
196
207
|
| `.agents/*.md` | Project | Shared |
|
|
197
208
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
| `mode` | TUI selector | `subagent` tool | `set_agent` tool |
|
|
201
|
-
|--------|-------------|-----------------|------------------|
|
|
202
|
-
| `primary` | ✅ visible | ❌ | ✅ |
|
|
203
|
-
| `subagent` | ❌ | ✅ available | ✅ |
|
|
204
|
-
| `all` (default) | ✅ visible | ✅ available | ✅ |
|
|
209
|
+
---
|
|
205
210
|
|
|
206
211
|
## Usage
|
|
207
212
|
|
|
@@ -224,36 +229,23 @@ Agents are loaded from multiple locations (project overrides global by name):
|
|
|
224
229
|
| `search_agents` | Search agents by name/description/body |
|
|
225
230
|
| `subagent` | Delegate task to a subagent (subagent/all mode only) |
|
|
226
231
|
|
|
227
|
-
|
|
232
|
+
---
|
|
228
233
|
|
|
229
|
-
|
|
230
|
-
2. Remove `npm:pi-agent-mode` and `npm:@johnnywu/pi-subagents` from settings
|
|
231
|
-
3. Existing agent `.md` files work without changes (default `mode: all`)
|
|
232
|
-
4. Gradually add `mode: primary` or `mode: subagent` to control visibility
|
|
233
|
-
5. Gradually adopt `permission:` over `tools:` whitelist
|
|
234
|
+
## Migration
|
|
234
235
|
|
|
235
|
-
|
|
236
|
+
```bash
|
|
237
|
+
pi install pi-open-agents
|
|
238
|
+
```
|
|
236
239
|
|
|
237
|
-
|
|
238
|
-
|
|
240
|
+
Remove `npm:pi-agent-mode` and `npm:@johnnywu/pi-subagents` from `settings.json`.
|
|
241
|
+
Existing agent `.md` files work without changes.
|
|
239
242
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
mode: subagent
|
|
245
|
-
model: openai/gpt-4o
|
|
246
|
-
tools:
|
|
247
|
-
read: true
|
|
248
|
-
bash: false
|
|
249
|
-
description: Triages issues by reading and categorizing them.
|
|
250
|
-
---
|
|
251
|
-
You are an issue triage agent...
|
|
252
|
-
```
|
|
243
|
+
Optional cleanup:
|
|
244
|
+
|
|
245
|
+
1. Add `mode: primary` or `mode: subagent` to agent files for explicit visibility
|
|
246
|
+
2. Gradually adopt `permission:` over the old `tools:` whitelist
|
|
253
247
|
|
|
254
|
-
|
|
255
|
-
`false` → `deny`). Fields that are pi-specific (`thinking`, `maxDepth`,
|
|
256
|
-
`allowedAgents`) are ignored by OpenCode without breaking.
|
|
248
|
+
---
|
|
257
249
|
|
|
258
250
|
## Development
|
|
259
251
|
|
|
@@ -271,6 +263,8 @@ docker compose run --rm pi-sandbox
|
|
|
271
263
|
|
|
272
264
|
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical design.
|
|
273
265
|
|
|
266
|
+
---
|
|
267
|
+
|
|
274
268
|
## Attribution
|
|
275
269
|
|
|
276
270
|
This project builds on code and ideas from:
|