oira666_pi-subagent 0.1.2 → 0.1.3

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.
Files changed (2) hide show
  1. package/README.md +59 -261
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,326 +1,124 @@
1
1
  # Pi Subagent
2
2
 
3
- **Delegate tasks to specialized subagents with configurable context modes (`spawn` / `fork`).**
4
-
5
- There are many subagent extensions for pi, this one is mine.
6
-
7
- ## Why Pi Subagent
8
-
9
- **Specialization** — Use tailored agents for specific tasks like refactoring, documentation, or research.
10
-
11
- **Context Control** — Choose `spawn` (fresh context) or `fork` (inherit current session context), depending on the task.
12
-
13
- **Parallel Execution** — Run multiple agents at once.
14
-
15
- **A Simpler Fork** — This extension intentionally keeps the surface area small and predictable compared to heavier implementations. It supports nested delegation with depth/cycle guards, but avoids broader scope-selection complexity. If you want the minimal, “just delegate” experience, this is it.
3
+ Delegate tasks to specialized subagents with configurable context modes (`spawn` / `fork`).
16
4
 
17
5
  ## Install
18
6
 
19
- ### Option 1: Install from npm (recommended)
20
-
21
7
  ```bash
22
8
  pi install npm:oira666_pi-subagent
23
9
  ```
24
10
 
25
- ### Option 2: Install via git
11
+ Or via git:
26
12
 
27
13
  ```bash
28
14
  pi install git:github.com/gee666/pi-subagent.git
29
15
  ```
30
16
 
31
- ### Option 3: Manual Installation
32
-
33
- Clone this repository to your Pi extensions directory:
34
-
35
- ```bash
36
- cd ~/.pi/agent/extensions
37
- git clone https://github.com/gee666/pi-subagent.git
38
- cd pi-subagent
39
- npm install
40
- ```
41
-
42
- ## Configuration
43
-
44
- ### Delegation Guards (Depth + Cycle Prevention)
45
-
46
- By default, this extension enforces two runtime guards:
47
-
48
- 1. **Depth guard** (`--subagent-max-depth`, default `3`)
49
- - Main agent starts at depth `0`
50
- - Delegation is allowed while `currentDepth < maxDepth`
51
- - With default depth `3`: depth `0`, `1`, and `2` can delegate; depth `3` cannot
52
- 2. **Cycle guard** (`--subagent-prevent-cycles`, default `true`)
53
- - Blocks delegating to any agent name already present in the current delegation stack
54
- - Prevents self-recursion (`writer -> writer`) and loops (`planner -> reviewer -> planner`)
55
-
56
- You can configure depth with either:
57
-
58
- - CLI flag: `--subagent-max-depth <n>`
59
- - Environment variable: `PI_SUBAGENT_MAX_DEPTH=<n>`
60
-
61
- `n` must be a non-negative integer.
62
-
63
- You can configure cycle prevention with either:
64
-
65
- - CLI flag: `--subagent-prevent-cycles` / `--no-subagent-prevent-cycles`
66
- - Environment variable: `PI_SUBAGENT_PREVENT_CYCLES=true|false`
67
-
68
- Internal env vars managed by the extension and propagated to child processes:
69
-
70
- - `PI_SUBAGENT_DEPTH`
71
- - `PI_SUBAGENT_MAX_DEPTH`
72
- - `PI_SUBAGENT_STACK` (JSON array of ancestor agent names, e.g. `["scout","planner"]`)
73
- - `PI_SUBAGENT_PREVENT_CYCLES`
74
-
75
- Examples:
17
+ ## Remove
76
18
 
77
19
  ```bash
78
- # Default behavior: depth 3 + cycle prevention enabled
79
- pi
80
-
81
- # Restrict to one nested level (main -> child -> grandchild)
82
- pi --subagent-max-depth 2
83
-
84
- # Disable subagent delegation entirely
85
- pi --subagent-max-depth 0
86
-
87
- # Allow depth 3 but disable cycle prevention (not recommended)
88
- pi --subagent-max-depth 3 --no-subagent-prevent-cycles
20
+ pi remove npm:oira666_pi-subagent
89
21
  ```
90
22
 
91
- ### Tool Call Shape
23
+ ## How It Works
92
24
 
93
- `subagent` always accepts a top-level `tasks` array:
25
+ Each subagent runs as a **separate `pi` process** — isolated memory, its own model/tool loop.
94
26
 
95
- - One task = single-agent delegation
96
- - Multiple tasks = parallel delegation
27
+ **`spawn` (default)** — Child receives only the task string. Best for isolated work, lower cost.
28
+ **`fork`** — Child receives a snapshot of the current session context + task. Best for follow-up work.
97
29
 
98
- Single-task example:
30
+ The main agent receives only the **final text output** from subagents (no tool calls, no reasoning).
99
31
 
100
- ```json
101
- { "tasks": [{ "agent": "code-writer", "task": "Implement the API change" }], "mode": "spawn" }
102
- ```
103
-
104
- Multi-task example:
32
+ ## Tool Call Shape
105
33
 
106
34
  ```json
107
- { "tasks": [{ "agent": "code-writer", "task": "Draft the implementation" }, { "agent": "code-reviwer", "task": "Review the plan" }], "mode": "fork" }
35
+ { "tasks": [{ "agent": "code-writer", "task": "Implement the API" }], "mode": "spawn" }
108
36
  ```
109
37
 
110
- Each task item supports:
111
-
112
- - `agent` — subagent name
113
- - `task` — delegated task text
114
- - `cwd` — optional working directory override for that task
115
-
116
- ### Parallel Execution Limits
117
-
118
- For multi-task calls, two environment variables control fan-out:
119
-
120
- - `PI_SUBAGENT_MAX_PARALLEL_TASKS` — maximum number of tasks allowed in one call (default: `16`)
121
- - `PI_SUBAGENT_MAX_CONCURRENCY` — maximum number of subagents running at the same time inside that call (default: `8`)
122
-
123
- `PI_SUBAGENT_MAX_CONCURRENCY` is effectively clamped to at least `1`.
124
-
125
- ### Project-local Agent Confirmation
126
-
127
- Project-local agents from `.pi/agents/*.md` can be gated by `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`:
128
-
129
- - `true`, `ask`, or `once` (default) — prompt with **Yes once**, **Yes for this session**, or **No**
130
- - `false` or `never` — skip the prompt and allow project-local agents immediately
131
- - `session` — allow project-local agents for the rest of the current session without prompting
132
-
133
- If you choose **Yes for this session** in the UI, the choice is remembered and you will not be asked again in that session. In non-UI mode, `ask` blocks execution because the extension cannot prompt.
134
-
135
- ### Context Mode (`spawn` vs `fork`)
136
-
137
- `subagent` supports a top-level `mode` switch:
138
-
139
- - `spawn` (default) — Child receives only the task string (`Task: ...`). Best for isolated, reproducible work; typically lower token/cost and less context leakage.
140
- - `fork` — Child receives a forked snapshot of the current session context **plus** the task string. Best for follow-up work that depends on prior context; typically higher token/cost and may include sensitive context.
141
-
142
- Quick rule of thumb:
143
-
144
- - Start with `spawn` for one-off tasks.
145
- - Use `fork` when the delegated task depends on the current session's prior discussion, reads, or decisions.
146
-
147
- Examples:
38
+ Multiple tasks run in parallel:
148
39
 
149
40
  ```json
150
- { "tasks": [{ "agent": "code-writer", "task": "Implement the migration" }], "mode": "spawn" }
41
+ {
42
+ "tasks": [
43
+ { "agent": "code-writer", "task": "Draft the implementation" },
44
+ { "agent": "code-reviwer", "task": "Review the plan" }
45
+ ],
46
+ "mode": "fork"
47
+ }
151
48
  ```
152
49
 
153
- ```json
154
- { "tasks": [{ "agent": "code-reviwer", "task": "Double-check this migration" }], "mode": "fork" }
155
- ```
156
-
157
- If omitted, mode defaults to `spawn`.
158
-
159
- ### Subagent Definitions
160
-
161
- Subagents are defined as Markdown files with YAML frontmatter.
162
-
163
- **User Agents:** `~/.pi/agent/agents/*.md`
164
- **Project Agents:** `.pi/agents/*.md`
165
- **Bundled Fallback Agents:** `agents/code-writer.md`, `agents/code-reviwer.md`, `agents/code-architect.md`
50
+ Each task supports `agent`, `task`, and optional `cwd`.
166
51
 
167
- The extension always loads user and project agents first. If a project agent shares a name with a user agent, the project agent wins. The bundled fallback agents are only discovered when no user or project agents are found at all. If you have any user or project agents configured, the bundled defaults are hidden and not discoverable. When project agents are requested, Pi can prompt for confirmation before running them, depending on `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`.
52
+ ## Bundled Agents
168
53
 
169
- If nothing is configured yet, these fallback agents are available by default:
54
+ Three fallback agents ship with the extension (used when no user/project agents are configured):
170
55
 
171
56
  - `code-writer` — implementation and refactoring
172
57
  - `code-reviwer` — code review and risk finding
173
58
  - `code-architect` — technical design and approach selection
174
59
 
175
- Example agent (`~/.pi/agent/agents/writer.md`):
60
+ ## Defining Agents
61
+
62
+ Create Markdown files with YAML frontmatter:
63
+
64
+ - **User agents:** `~/.pi/agent/agents/*.md`
65
+ - **Project agents:** `.pi/agents/*.md` *(may prompt for confirmation — see `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`)*
176
66
 
177
67
  ```markdown
178
68
  ---
179
69
  name: writer
180
- description: Expert technical writer and editor
70
+ description: Expert technical writer
181
71
  model: anthropic/claude-3-5-sonnet
182
- tools: read, write
72
+ thinking: low
73
+ tools: read,write
183
74
  ---
184
75
 
185
- You are an expert technical writer. Your task is to improve the clarity and conciseness of the provided text.
76
+ You are an expert technical writer focused on clarity and conciseness.
186
77
  ```
187
78
 
188
- Note: this repository includes bundled fallback agents in `agents/code-writer.md`, `agents/code-reviwer.md`, and `agents/code-architect.md`.
189
-
190
79
  ### Frontmatter Fields
191
80
 
192
- | Field | Required | Default | Description |
193
- | ------------- | -------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
194
- | `name` | Yes | — | Agent identifier used in tool calls (must match exactly) |
195
- | `description` | Yes | — | What the agent does (shown to the main agent) |
196
- | `model` | No | Uses the default pi model | Overrides the model for this agent. You can include a provider prefix (e.g. `anthropic/claude-3-5-sonnet` or `openrouter/claude-3.5-sonnet`) to force a specific provider. |
197
- | `thinking` | No | Uses Pi's default thinking level | Sets the thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). Equivalent to `--thinking`. |
198
- | `tools` | No | `read,bash,edit,write` | Comma-separated list of **built-in** tools to enable for this agent. If omitted, defaults apply. |
199
-
200
- Notes:
201
-
202
- - `model` accepts `provider/model` syntax — this is a Pi feature. Use it when multiple providers offer the same model ID.
203
- - `thinking` uses the same values as Pi's `--thinking` flag; it's recommended to set it explicitly since thinking support varies by model.
204
- - `tools` only controls built-in tools. Extension tools remain available unless extensions are disabled.
205
- - The Markdown body below the frontmatter becomes the agent's system prompt and is **appended** to Pi's default system prompt (it does **not** replace it).
206
-
207
- ### Writing a Good Agent File
208
-
209
- - **Description matters** — the main agent uses the `description` to decide which subagent to call, so be specific about what the agent is good at.
210
- - **Tool scope is optional but helpful** — reducing tools can keep the agent focused, but you can leave defaults if unsure.
211
- - **Model + thinking is the power combo** — selecting the right model and thinking level is often the biggest quality boost.
212
-
213
- ### Available Built-in Tools
214
-
215
- Available Tools (default: `read`, `bash`, `edit`, `write`):
216
-
217
- - `read` — Read file contents
218
- - `bash` — Execute bash commands
219
- - `edit` — Edit files with find/replace
220
- - `write` — Write files (creates/overwrites)
221
- - `grep` — Search file contents (read-only, off by default)
222
- - `find` — Find files by glob pattern (read-only, off by default)
223
- - `ls` — List directory contents (read-only, off by default)
224
-
225
- Tip: for a read-only tool selection, use `read,find,ls,grep`. As soon as you include `edit`, `write`, or `bash`, the agent can practically go wild.
226
-
227
- ## How Communication Works
228
-
229
- ### The Isolation Model
230
-
231
- Each subagent always runs in a **separate `pi` process**:
232
-
233
- - ❌ No shared memory/state with the parent process
234
- - ❌ No visibility into sibling subagents
235
- - ✅ Its own model/tool/runtime loop
236
- - ✅ Started with `PI_OFFLINE=1` to skip startup network operations and reduce spawn latency
237
-
238
- What it can see depends on `mode`:
81
+ | Field | Required | Default | Description |
82
+ | ------------- | -------- | -------------------- | -------------------------------------------------------- |
83
+ | `name` | Yes | — | Agent identifier used in tool calls |
84
+ | `description` | Yes | — | What the agent does (shown to the main agent) |
85
+ | `model` | No | Pi default | Override model, e.g. `anthropic/claude-3-5-sonnet` |
86
+ | `thinking` | No | Pi default | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
87
+ | `tools` | No | `read,bash,edit,write` | Comma-separated built-in tools |
239
88
 
240
- - `spawn` (default)
241
- - ✅ Receives: subagent system prompt + `Task: ...`
242
- - ❌ Does **not** receive parent session history
243
- - `fork`
244
- - ✅ Receives: forked snapshot of current parent session context + `Task: ...`
89
+ Available tools: `read`, `bash`, `edit`, `write`.
245
90
 
246
- ### What Gets Sent to Subagents
91
+ The Markdown body becomes the agent's system prompt (appended to Pi's default, not replacing it).
247
92
 
248
- #### `spawn` mode (default)
93
+ ## Delegation Guards
249
94
 
250
- `subagent({ tasks: [{ agent: "writer", task: "Document the API" }] })` sends:
95
+ Depth and cycle guards prevent runaway recursive delegation.
251
96
 
252
- ```
253
- [System Prompt from ~/.pi/agent/agents/writer.md]
254
-
255
- User: Task: Document the API
256
- ```
257
-
258
- No parent conversation history is included. In `spawn`, include all required context in `task`.
259
-
260
- #### `fork` mode
261
-
262
- `subagent({ tasks: [{ agent: "writer", task: "Document the API" }], mode: "fork" })` sends:
263
-
264
- ```
265
- [Forked snapshot of current session context]
266
- [System Prompt from ~/.pi/agent/agents/writer.md]
267
-
268
- User: Task: Document the API
269
- ```
270
-
271
- Note: `fork` copies session context, not transient runtime-only prompt mutations from the parent process.
97
+ | Config | Default | Description |
98
+ | ------------------------------ | ------- | ------------------------------------------------ |
99
+ | `--subagent-max-depth` / `PI_SUBAGENT_MAX_DEPTH` | `3` | Max delegation depth (0 disables delegation) |
100
+ | `--subagent-prevent-cycles` / `PI_SUBAGENT_PREVENT_CYCLES` | `true` | Block same agent in delegation chain |
272
101
 
273
- ### What Comes Back to the Main Agent
274
-
275
- | Data | Main Agent Sees | TUI Shows |
276
- | --------------------------- | ------------------------ | ---------------------- |
277
- | Final text output | ✅ Yes — full, unbounded | ✅ Yes |
278
- | Tool calls made by subagent | ❌ No | ✅ Yes (expanded view) |
279
- | Token usage / cost | ❌ No | ✅ Yes |
280
- | Reasoning/thinking steps | ❌ No | ❌ No |
281
- | Error messages | ✅ Yes (on failure) | ✅ Yes |
282
-
283
- **Key point:** The main agent receives **only the final assistant text** from each subagent. Not the tool calls, not the reasoning, not the intermediate steps. This prevents context pollution while still giving you the results.
284
-
285
- ### Parallel Mode Behavior
286
-
287
- When running multiple agents in parallel:
288
-
289
- - Subagents run concurrently up to `PI_SUBAGENT_MAX_CONCURRENCY` (default `8`)
290
- - The top-level `mode` applies to all tasks in that call
291
- - Main agent receives a combined result after all finish:
292
-
293
- ```
294
- Parallel: 3/3 succeeded
295
-
296
- [writer] completed: Full output text here...
297
- [tester] completed: Full output text here...
298
- [reviewer] completed: Full output text here...
102
+ ```bash
103
+ pi --subagent-max-depth 2 # one nested level
104
+ pi --subagent-max-depth 0 # disable delegation entirely
105
+ pi --no-subagent-prevent-cycles # allow cycles (not recommended)
299
106
  ```
300
107
 
301
- ## Features
108
+ ## Parallel Limits
302
109
 
303
- - **Auto-Discovery** — Agents are found at startup and their descriptions are injected into the main agent's system prompt.
304
- - **Context Mode Switch** — `spawn` (fresh context) and `fork` (session snapshot + task) per call.
305
- - **Depth + Cycle Guards** — Depth limiting and ancestry-cycle checks prevent runaway recursive delegation by default.
306
- - **Streaming Updates** — Watch subagent progress in real-time as tool calls and outputs stream in.
307
- - **Nested Delegation** — Subagents can call `subagent` again, subject to depth and cycle guards.
308
- - **Rich TUI Rendering** — Collapsed/expanded views with usage stats, nested delegation trees, tool call previews, and markdown output.
309
- - **Security Confirmation** — Project-local agents can require explicit user approval, with one-time and session-wide approval options.
110
+ | Env Var | Default | Description |
111
+ | -------------------------------- | ------- | ---------------------------------------- |
112
+ | `PI_SUBAGENT_MAX_PARALLEL_TASKS` | `16` | Max tasks per single call |
113
+ | `PI_SUBAGENT_MAX_CONCURRENCY` | `8` | Max subagents running simultaneously |
310
114
 
311
- ## Project Structure
115
+ ## create-subagent Skill
312
116
 
313
- ```
314
- index.ts — Extension entry point: lifecycle hooks, tool registration, mode orchestration
315
- agents.ts — Agent discovery: reads and parses .md files from user/project directories
316
- runner.ts — Process runner: starts `pi` subprocesses in spawn/fork context modes and streams JSON events
317
- render.ts — TUI rendering: renderCall and renderResult for the subagent tool
318
- types.ts — Shared types and pure helper functions
319
- ```
117
+ If you want the agent to **create new subagent definition files** for itself, install the [`create-subagent` skill](https://github.com/gee666/pi-subagent/tree/main/create-subagent). Once installed, the agent will know how to scaffold new `.md` agent files in the right location with correct frontmatter.
320
118
 
321
119
  ## Attribution
322
120
 
323
- Inspired by implementations from [vaayne/agent-kit](https://github.com/vaayne/agent-kit) and [mariozechner/pi-mono](https://github.com/badlogic/pi-mono).
121
+ Inspired by [vaayne/agent-kit](https://github.com/vaayne/agent-kit) and [mariozechner/pi-mono](https://github.com/badlogic/pi-mono).
324
122
 
325
123
  ## License
326
124
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oira666_pi-subagent",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
5
5
  "type": "module",
6
6
  "main": "index.ts",