@pi-archimedes/subagent 2.5.1 → 2.6.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.
- package/README.md +71 -57
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,103 +1,117 @@
|
|
|
1
1
|
# @pi-archimedes/subagent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Give your agent some backup.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Big thinking and multi-file refactors are expensive to do in the main line. Subagent lets your agent delegate that work: it dispatches child agents — singly or in parallel — with a model and tool set of your choice per role, streams their progress live, and books their tokens and costs into the same status bar. You watch the whole team at once.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- **Live TUI streaming** — watch subagent progress in real-time with color-coded tool calls (grey while running, green/red on completion), readable argument previews, token counts, and cost updates
|
|
11
|
-
- **Agent discovery** — auto-discovers agents from `.pi/agents/*.md` files at project, user, and global scope
|
|
12
|
-
- **Per-agent model override** — each subagent can use its own model, falling back to the parent's selection
|
|
13
|
-
- **Cost tracking** — detailed token usage (input, output, cache read/write) and cost per subagent, emitted through the core bus for the footer to consume
|
|
14
|
-
- **Trace correlation** — results expose the ephemeral child's logical Pi session UUID as optional `childSessionId` when Pi emits a valid session event
|
|
15
|
-
- **`/agents` command** — full CRUD TUI for managing agent definitions with model picker, tool picker, and cross-scope collision warnings (available via the meta package)
|
|
9
|
+
Standalone:
|
|
16
10
|
|
|
17
|
-
|
|
11
|
+
```bash
|
|
12
|
+
pi install npm:@pi-archimedes/subagent
|
|
13
|
+
```
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
Or the full suite instead:
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
```bash
|
|
18
|
+
pi install npm:pi-archimedes
|
|
19
|
+
```
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0:
|
|
24
22
|
|
|
25
|
-
|
|
23
|
+
```bash
|
|
24
|
+
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
|
|
25
|
+
```
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
After installing Pi, choose one installation command above, then `cd` into your project and run `pi`. Inside the session, `/login` signs you in and `/model` picks a model — the [setup section](https://github.com/danielcherubini/pi-archimedes#setup) covers the first run. `/reload` picks the dispatch tool up in a running session.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
<div align="center">
|
|
30
|
+
<img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/subagents-main-view.png" width="750" alt="Subagents parallel streaming view">
|
|
31
|
+
</div>
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
## Dispatching
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
### Config-less — omit `agent`
|
|
34
36
|
|
|
35
|
-
|
|
37
|
+
The `agent` field is optional — omitting it is not a built-in default agent, and **no agents are shipped** with the package. Without an agent file, the model falls back to the per-call `model` override and then the parent's active model, and tools follow Pi's normal selection at spawn — except the `subagent` tool itself is always excluded, so a worker can't spawn workers:
|
|
36
38
|
|
|
37
|
-
|
|
39
|
+
```jsonc
|
|
40
|
+
{
|
|
41
|
+
"task": "review the uncommitted changes and list the risks",
|
|
42
|
+
"model": "openrouter/anthropic/claude-sonnet-4", // optional per-call override
|
|
43
|
+
"cwd": "/path/to/project" // optional working directory
|
|
44
|
+
}
|
|
45
|
+
```
|
|
38
46
|
|
|
39
|
-
|
|
47
|
+
**The dispatch waits.** A call — single or parallel — blocks until every task completes and returns the combined results, each optionally carrying the child's `childSessionId`. There is an `async` field in the schema; the implementation ignores it, so don't plan on fire-and-forget: batch the work into `tasks` and let the call block on all of it.
|
|
40
48
|
|
|
41
|
-
|
|
49
|
+
### Model and thinking resolution
|
|
42
50
|
|
|
43
|
-
|
|
51
|
+
Per dispatch, the model resolves in order: **the agent config's `model`, then the per-call `model`, then the parent's active model** (the first entry doesn't apply to config-less dispatch).
|
|
44
52
|
|
|
45
|
-
|
|
46
|
-
pi install npm:@pi-archimedes/subagent
|
|
47
|
-
```
|
|
53
|
+
The thinking level is **not** inherited from the parent session's active thinking. It comes from the agent file's explicit `thinking` when present; otherwise Pi works out its own (the selected model, its configuration, or the model's default).
|
|
48
54
|
|
|
49
|
-
|
|
55
|
+
## Agent files
|
|
50
56
|
|
|
51
|
-
|
|
52
|
-
|
|
57
|
+
Named agents are `.md` files with YAML frontmatter — a complete definition:
|
|
58
|
+
|
|
59
|
+
```markdown
|
|
60
|
+
---
|
|
61
|
+
name: reviewer
|
|
62
|
+
description: Reviews diffs and flags risks before code lands
|
|
63
|
+
model: openrouter/anthropic/claude-sonnet-4
|
|
64
|
+
tools: read, bash
|
|
65
|
+
thinking: medium
|
|
66
|
+
---
|
|
67
|
+
You are a meticulous code reviewer. Read the diff, flag real risks,
|
|
68
|
+
and name the lines you checked.
|
|
53
69
|
```
|
|
54
70
|
|
|
55
|
-
|
|
71
|
+
- `name` and `description` are **required** — a file without them is skipped. `tools` is a **comma-separated string**. The markdown body is the agent's system prompt.
|
|
72
|
+
- **Scopes, in precedence order:** project (`<repo>/.pi/agents/`), user (`~/.pi/agent/agents/`), and global — the repository's `.agents/agents/` or, falling back, `~/.agents/agents/`.
|
|
73
|
+
- Unknown frontmatter fields are preserved on edit, not interpreted.
|
|
74
|
+
- Model and thinking picked in the `/agents` TUI are saved to `~/.pi/agent/agents.local.json` (machine-local, not committed), take precedence over the frontmatter, and are stripped from the `.md` on save. Hand-written `model:`/`thinking:` in frontmatter remain the fallback.
|
|
56
75
|
|
|
57
|
-
###
|
|
76
|
+
### Named agents
|
|
58
77
|
|
|
59
|
-
|
|
78
|
+
With an `agent` name, the dispatch runs under that defined agent file — no agents are bundled, so the name must exist in one of these files. Unknown names are refused and list the available agents, so a typo fails cheap:
|
|
60
79
|
|
|
61
80
|
```jsonc
|
|
62
81
|
{
|
|
63
|
-
"agent": "reviewer",
|
|
64
|
-
"task": "review the PR"
|
|
65
|
-
"model": "openrouter/anthropic/claude-4", // optional override
|
|
66
|
-
"cwd": "/path/to/dir" // optional working directory
|
|
82
|
+
"agent": "reviewer",
|
|
83
|
+
"task": "review the PR diff"
|
|
67
84
|
}
|
|
68
85
|
```
|
|
69
86
|
|
|
70
|
-
Parallel
|
|
87
|
+
### Parallel work
|
|
88
|
+
|
|
89
|
+
Independent tasks go in a `tasks` array — mix defined agents and config-less tasks, distinct models, one call:
|
|
71
90
|
|
|
72
91
|
```jsonc
|
|
73
92
|
{
|
|
74
93
|
"tasks": [
|
|
75
|
-
{ "agent": "
|
|
76
|
-
{ "
|
|
94
|
+
{ "agent": "reviewer", "task": "review the proposed migration plan" },
|
|
95
|
+
{ "task": "find all usages of the deprecated API" } // config-less — the model/tools fall back as above
|
|
77
96
|
]
|
|
78
97
|
}
|
|
79
98
|
```
|
|
80
99
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
Run `/agents` to open the interactive Agents Manager for creating, editing, and deleting agent definitions.
|
|
84
|
-
|
|
85
|
-
## Agent files
|
|
86
|
-
|
|
87
|
-
Agents are defined as `.md` files with YAML frontmatter, placed in one of:
|
|
88
|
-
|
|
89
|
-
- **Project scope:** `<repo root>/.pi/agents/` — available only in this project
|
|
90
|
-
- **User scope:** `~/.pi/agent/agents/` — available across all projects
|
|
91
|
-
- **Global scope:** `<repo root>/.agents/agents/` or `~/.agents/agents/` — shared or installed subagents
|
|
100
|
+
## The `/agents` command
|
|
92
101
|
|
|
93
|
-
|
|
102
|
+
Available with the suite (and subagent enabled), `/agents` opens the interactive manager: a searchable list, model and tool pickers, cross-scope collision warnings, and dirty-tracking on save.
|
|
94
103
|
|
|
95
|
-
|
|
104
|
+
<p align="center">
|
|
105
|
+
<img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/subagents-agent-view.png" width="650" alt="Subagents agent details view">
|
|
106
|
+
</p>
|
|
96
107
|
|
|
97
|
-
|
|
108
|
+
<p align="center">
|
|
109
|
+
<img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/subagents-model-selection.png" width="48%" alt="Model selection">
|
|
110
|
+
<img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/subagents-tool-selection.png" width="48%" alt="Tool selection">
|
|
111
|
+
</p>
|
|
98
112
|
|
|
99
|
-
|
|
113
|
+
## Part of the suite
|
|
100
114
|
|
|
101
|
-
The
|
|
115
|
+
The full suite is the supported connected setup. With the relevant components loaded together, subagent token and cost events flow over core's bus into the footer, subagent tasks get their own columns on the todo board, and subagent `ask` questions surface in your terminal. On/off is managed by the suite: toggle via `/plugins` (`archimedes.subagent.enabled`, default on).
|
|
102
116
|
|
|
103
|
-
← Back to
|
|
117
|
+
← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pi-archimedes/subagent",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.6.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package"
|
|
@@ -11,8 +11,8 @@
|
|
|
11
11
|
],
|
|
12
12
|
"main": "./src/index.ts",
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@pi-archimedes/
|
|
15
|
-
"@pi-archimedes/
|
|
14
|
+
"@pi-archimedes/core": "2.6.3",
|
|
15
|
+
"@pi-archimedes/todo": "2.6.3"
|
|
16
16
|
},
|
|
17
17
|
"peerDependencies": {
|
|
18
18
|
"@earendil-works/pi-ai": ">=0.1.0",
|
|
@@ -21,9 +21,9 @@
|
|
|
21
21
|
"typebox": ">=1.1.0"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
|
-
"@earendil-works/pi-ai": "^0.
|
|
25
|
-
"@earendil-works/pi-coding-agent": "^0.
|
|
26
|
-
"@earendil-works/pi-tui": "^0.
|
|
24
|
+
"@earendil-works/pi-ai": "^0.85.1",
|
|
25
|
+
"@earendil-works/pi-coding-agent": "^0.85.1",
|
|
26
|
+
"@earendil-works/pi-tui": "^0.85.1",
|
|
27
27
|
"@types/node": "^22.0.0",
|
|
28
28
|
"typebox": "^1.1.38",
|
|
29
29
|
"typescript": "^6.0.3"
|