# @nklisch/pi-subagents
[](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://pnpm.io/) [](https://pi.mariozechner.at/)
A [pi](https://pi.dev) extension that gives pi **a focused, in-process sub-agent core** — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on.
Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level.
Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
> A maintained MIT fork of [`@gotgenes/pi-subagents`](https://www.npmjs.com/package/@gotgenes/pi-subagents), preserving its upstream execution core while adding a generic ordered lifecycle-interceptor provider seam.
> See [Fork maintenance](./docs/FORK-MAINTENANCE.md) for provenance, qualification, and upstream-return policy.
## Features
- **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
- **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
- **Session transcripts** — open any subagent's full session transcript, including records whose heavy live session has been released, in pi's native read-only viewer via `/subagents:sessions`
- **Custom agent types** — define project agents in `.pi/agents/.md` or the shared `.agents/agents/.md` convention, with YAML frontmatter for prompts, models, thinking, and built-in tools
- **Mid-run steering** — inject messages into running agents to redirect their work without restarting
- **Session resume** — pick up where an agent left off, preserving full conversation context
- **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
- **Policy-aware agent types** — unambiguous names resolve case-insensitively. Unknown names default to `general-purpose`, can target another enabled fallback, or can fail closed via `fallbackSubagent`
- **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
- **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML.
Expandable to show full output
- **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `resumed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
## Install
This branch is locally qualified but unpublished, so it cannot be installed from npm yet.
After an explicitly authorized publication, the package name will be `@nklisch/pi-subagents` and its immutable registry receipt will be recorded in [Fork maintenance](./docs/FORK-MAINTENANCE.md).
Load it directly for development:
```bash
pi -e ./src/index.ts
```
## Quick Start
The parent agent spawns sub-agents using the `subagent` tool:
```text
subagent({
subagent_type: "Explore",
prompt: "Find all files that handle authentication",
description: "Find auth files",
run_in_background: true,
})
```
Foreground agents block until complete and return results inline.
Background agents return an ID immediately and notify you on completion.
## UI
The extension renders a persistent widget above the editor showing active background agents (foreground runs are rendered inline by the `subagent` tool's progress stream):
```text
● Agents
├─ ⠹ Agent Refactor auth module · ⟳5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s
│ ⎿ editing 2 files…
├─ ⠹ Explore Find auth files · ⟳3 · 3 tool uses · 12.4k token (8%) · 4.1s
│ ⎿ searching…
├─ ⠹ Agent Long-running task · ⟳42 · 38 tool uses · 91.0k token (84% · ↻2) · 2m17s
│ ⎿ reading…
└─ 2 queued
```
The token field is annotated with two optional signals inside parens:
- **`NN%`** — context-window utilization (color-coded: <70% dim, 70–85% warning, ≥85% error).
Omitted when the model has no declared `contextWindow`, or briefly right after compaction.
- **`↻N`** — number of times the session has compacted, when > 0.
Stays dim; the percent's color carries urgency.
Individual agent results render inline in the conversation:
| State | Example |
| -------------- | ---------------------------------------------------------------------------------------- |
| **Running** | `⠹ ⟳3≤30 · 3 tool uses · 12.4k token (8%)` / `⎿ searching, reading 3 files…` |
| **Completed** | `✓ ⟳8 · 5 tool uses · 33.8k token (62%) · 12.3s` / `⎿ Done` |
| **Wrapped up** | `✓ ⟳50≤50 · 50 tool uses · 89.1k token (84% · ↻2) · 45.2s` / `⎿ Wrapped up (turn limit)` |
| **Stopped** | `■ ⟳3 · 3 tool uses · 12.4k token (8%)` / `⎿ Stopped` |
| **Error** | `✗ ⟳3 · 3 tool uses · 12.4k token (8%)` / `⎿ Error: timeout` |
| **Aborted** | `✗ ⟳55≤50 · 55 tool uses · 102.3k token (95% · ↻3)` / `⎿ Aborted (max turns exceeded)` |
Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
Background agent completion notifications render as styled boxes:
```text
✓ Find auth files completed
⟳3 · 3 tool uses · 12.4k token · 4.1s
⎿ Found 5 files related to authentication...
transcript: .pi/output/agent-abc123.jsonl
```
The LLM receives structured `` XML for parsing, while the user sees the themed visual.
## Default Agent Types
| Type | Tools | Model | Prompt Mode | Description |
| ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| `general-purpose` | all 7 | inherit | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions |
| `Explore` | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace` | Fast codebase exploration (read-only); inherits the parent prompt as a base |
The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does.
Explore uses `replace` mode: the parent prompt is the cacheable base and its specialist read-only instructions are appended last, giving those instructions the final say.
Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
## Custom Agents
Define custom agent types by creating `.md` files.
The filename becomes the agent type name.
Any name is allowed — using a default agent's name overrides it.
Agents are discovered from three locations (higher priority wins):
| Priority | Location | Scope |
| ----------- | -------------------------------------------------------------------------------- | -------------------------------------- |
| 1 (highest) | `.pi/agents/.md` | Pi project authority |
| 2 | `.agents/agents/.md` | Shared cross-tool project definitions |
| 3 | `$PI_CODING_AGENT_DIR/agents/.md` (default `~/.pi/agent/agents/.md`) | Global — available everywhere |
`.agents/agents` is read-only to this extension. `.pi/agents` overrides it and the global location on name collisions.
The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
### Example: `.pi/agents/auditor.md`
```markdown
---
description: Security Code Reviewer
tools: read, grep, find, bash
model: anthropic/claude-opus-4-6
thinking: high
max_turns: 30
---
You are a security auditor.
Review code for vulnerabilities including:
- Injection flaws (SQL, command, XSS)
- Authentication and authorization issues
- Sensitive data exposure
- Insecure configurations
Report findings with file paths, line numbers, severity, and remediation advice.
```
Then spawn it like any built-in type:
```text
subagent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
```
### Frontmatter Fields
All fields are optional — sensible defaults for everything.
| Field | Default | Description |
| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | filename | Agent description shown in tool listings |
| `display_name` | — | Display name for UI (e.g. widget, agent list) |
| `tools` | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` denies all built-ins. Parent extension tools remain inheritable and are narrowed by extension policy |
| `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
| `thinking` | inherit | off, minimal, low, medium, high, xhigh, max (actual support depends on host and model) |
| `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
| `prompt_mode` | `append` | `replace`: parent prompt is the cacheable base; body is appended last with full control (no `` bridge, no `` wrapper). `append`: parent prompt is the base; body is wrapped in `` and a sub-agent context bridge is injected (agent acts as a "parent twin") |
| `inherit_context` | `false` | Fork parent conversation into agent |
| `run_in_background` | `false` | Run in background by default |
| `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
Frontmatter is authoritative.
If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, or `run_in_background`, those values are locked for that agent.
`subagent` tool parameters only fill fields the agent config leaves unspecified.
## Tools
### `subagent`
Launch a sub-agent.
| Parameter | Type | Required | Description |
| ------------------- | ------------ | -------- | ---------------------------------------------------------------- |
| `prompt` | string | yes | The task for the agent |
| `description` | string | yes | Short 3-5 word summary (shown in UI) |
| `subagent_type` | string | yes | Agent type (built-in or custom) |
| `model` | string | no | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
| `thinking` | string | no | Thinking level: off, minimal, low, medium, high, xhigh, max |
| `max_turns` | number | no | Max agentic turns. Omit for unlimited (default) |
| `run_in_background` | boolean | no | Run without blocking |
| `resume` | string | no | Retained, finished agent ID to continue with the same history |
| `inherit_context` | boolean | no | Fork parent conversation into agent |
### Choosing the next action
- Let background agents finish normally. Completion automatically wakes the parent with a result preview; do not poll.
- Use `steer_subagent` to redirect an agent that is still running.
- Use `resume` after an agent finishes when it should continue with the same retained conversation history.
- Launch a new subagent without `resume` when prior conversation history is unnecessary.
- Use `get_subagent_result` only for full output, verbose conversation, an explicit status check or synchronization point, or recovery after a missed notification.
### `get_subagent_result`
Inspect status or retrieve full results from a background agent. It is not the normal completion path because completion notifications wake the parent automatically.
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------------------------- |
| `agent_id` | string | yes | Agent ID to check |
| `wait` | boolean | no | Wait for completion |
| `verbose` | boolean | no | Include full conversation log |
### `steer_subagent`
Send a steering message to a running agent.
The message interrupts after the current tool execution.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------- |
| `agent_id` | string | yes | Agent ID to steer |
| `message` | string | yes | Message to inject into agent conversation |
## Commands
| Command | Description |
| --------------------- | ------------------------------------------------------ |
| `/subagents:settings` | Configure concurrency, turn limits, retention, interrupt behavior, and unknown-type fallback |
| `/subagents:sessions` | View a subagent's session transcript (read-only) |
### `/subagents:settings`
Interactive list to tune max concurrency, default/grace turns, consumed and unconsumed live-session retention, abort-all-on-ESC behavior, and unknown-agent fallback.
Changes persist across pi restarts (see [Persistent Settings](#persistent-settings)).
### `/subagents:sessions`
Pick any subagent — running, completed, or retained after its live session was released — and read its full session transcript in pi's native per-entry viewer.
Read-only: no steering, no session takeover (steering lives in the `steer_subagent` tool and the background widget).
Creating and editing agent definitions is not a command — write an agent `.md` file in your editor, or ask a pi session to generate one (see [Custom Agents](#custom-agents)).
## Graceful Max Turns
Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
1. At `max_turns` — steering message: *"Wrap up immediately — provide your final answer now."*
2. Up to 5 grace turns to finish cleanly
3. Hard abort only after the grace period
| Status | Meaning | Icon |
| ----------- | ----------------------------- | ---------- |
| `completed` | Finished naturally | `✓` green |
| `steered` | Hit limit, wrapped up in time | `✓` yellow |
| `aborted` | Grace period exceeded | `✗` red |
| `stopped` | User-initiated abort | `■` dim |
## Concurrency
Background agents are subject to a configurable concurrency limit (default: 4).
Excess agents are automatically queued and start as running agents complete. The widget shows each queued agent with its effective model and queued state. Stopping a queued agent follows the normal terminal lifecycle and reports that no work started.
Foreground agents bypass the queue — they block the parent anyway. Completion nudges are held while the parent is running and flushed at the parent run boundary, preventing a pulled result from also arriving as a duplicate notification.
Resume requests are serialized per retained session. A second request while a turn is genuinely active gets a deterministic busy result; after an abort or extension-driven continuation, resume waits for both the prior invocation and Pi's authoritative idle boundary instead of racing `AgentSession.prompt()`. Session teardown likewise emits and awaits `session_shutdown` before Pi revokes child extension contexts, allowing child-owned processes and timers to stop cleanly.
## Persistent Settings
Runtime tuning values set via `/subagents:settings` persist across pi restarts. Terminal records remain available for the whole parent session. Their heavy live sessions are released after the consumed or unconsumed retention window; the result and persisted transcript pointer remain available, but a released session cannot resume without starting a new subagent. A completion notification, foreground result, or `get_subagent_result` collection marks a result consumed, so the shorter consumed window normally governs after delivery.
Two files, merged on load:
- **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults.
Edit by hand; the `/subagents:settings` command never writes here.
- **Project:** `/.pi/subagents.json` — per-project overrides.
Written by `/subagents:settings`.
**Precedence:** project overrides global on any field present in both.
Missing fields use these defaults: max concurrency `4`, max turns unlimited, grace turns `5`, consumed-session retention `10` minutes, unconsumed-session retention `720` minutes, abort all on parent ESC enabled, and unknown-agent fallback `general-purpose`.
**Example — global defaults for a beefy machine:**
```bash
mkdir -p ~/.pi/agent
cat > ~/.pi/agent/subagents.json <<'EOF'
{
"maxConcurrent": 16,
"graceTurns": 10,
"unconsumedSessionRetentionMinutes": 1440,
"abortAllOnInterrupt": false,
"fallbackSubagent": false
}
EOF
```
Every project now starts with concurrency 16, grace 10, a one-day unconsumed retention cap, background agents surviving parent ESC, and unknown agent types failing closed.
Individual projects can still override via `/subagents:settings`.
**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/subagents:settings` toast to a warning with `(session only; failed to persist)`.
## Events
Agent lifecycle events are emitted via `pi.events.emit()` so other extensions can react:
| Event | When | Key fields |
| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `subagents:created` | Background agent registered | `id`, `type`, `description`, `isBackground` |
| `subagents:started` | Agent transitions to running (including queued→running) | `id`, `type`, `description` |
| `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens` (lifetime `{ input, output, total }`), `toolUses`, `result` |
| `subagents:resumed` | A resumed turn reached a terminal state | completed-event shape plus `status` and `error` |
| `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
| `subagents:steered` | Steering message sent | `id`, `message` |
| `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
| `subagents:settings_loaded` | Persisted settings applied at extension init | `settings` (merged global + project) |
| `subagents:settings_changed` | `/subagents:settings` mutation was applied | `settings`, `persisted` (`boolean` — `false` on write failure) |
`tokens.total` = `input + output + cacheWrite`.
`cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it.
Use `contextUsage.percent` (surfaced as `(NN%)` in the widget) for current context size.
## Worktree Isolation
Worktree isolation lives in a companion package, not this core.
Install [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees) and list the agent types you want isolated in its `worktreeAgents` config — opted-in agents run in a temporary git worktree, and their changes are saved to a branch on completion.
The earlier `isolation: "worktree"` spawn flag and `isolation:` frontmatter key were removed from the core.
## Removed: agent memory and skill preloading
Persistent agent memory (the `memory:` frontmatter key) and skill preloading (the `skills:` frontmatter key) were removed when the core was slimmed down.
Children always inherit the parent's skills and extensions, so the `isolated`, `extensions`, and `skills` frontmatter keys no longer exist. Child creation uses a denylist rather than a registration-time allowlist: extension tools—including tools registered during lifecycle hooks—remain available, while disallowed built-ins and the three recursive orchestration tools stay excluded.
## Migrating from `disallowed_tools`
The `disallowed_tools` frontmatter field has been removed.
Use [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system)'s `permission:` frontmatter instead — it provides richer semantics (allow/ask/deny vs. binary hide):
```yaml
# Before (no longer supported)
disallowed_tools: bash
# After
permission:
bash: deny
```
## Permission System Integration
When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) is installed, this extension integrates automatically:
- **Per-agent permission policies** — define `permission:` in agent YAML frontmatter to set allow/ask/deny rules per agent type.
The permission system resolves the agent name from the `` tag in the child system prompt.
- **Tool filtering** — the permission system's `before_agent_start` handler removes denied tools from the child session before the agent starts.
- **`ask`-state forwarding** — when a child session triggers an `ask` permission, the prompt forwards to the parent session's UI.
The parent approves or denies, and the child resumes.
- **Deterministic child detection** — this extension publishes `subagents:child:session-created` before `bindExtensions()` fires; the permission system subscribes and registers the child session synchronously, so detection does not rely on env vars or filesystem heuristics.
No configuration is required.
When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
## For Extension Authors
This package exposes two public subpath exports for companion extensions to import from the published tarball.
### `@nklisch/pi-subagents` — cross-extension service contract
Access the subagent service from another extension at runtime:
```typescript
const { getSubagentsService } = await import("@nklisch/pi-subagents");
const svc = getSubagentsService();
svc?.spawn("Explore", "Check for stale TODOs");
```
Declare this package as an optional peer dependency.
See `src/service/service.ts` for the full `SubagentsService` interface, the single `WorkspaceProvider`, and ordered lifecycle registration.
#### Ordered lifecycle interception
`registerLifecycleInterceptor()` is a generative provider seam for extensions that must replace or deny the exact child prompt, or accept, replace, abort, or continue a proposed child result before finalization.
Callbacks receive immutable agent/session/run/parent identity and execution-path facts, never a manager or live session.
Registrations are awaited in order; prompt and result replacements pipe to later providers; continuations stay in the same session and stop after three rounds.
Existing lifecycle events remain observational and cannot substitute for this registration API.
```typescript
const registration = svc?.registerLifecycleInterceptor({
beforeStart: async ({ prompt }) => ({ action: "continue", prompt: `Context:\n${prompt}` }),
beforeComplete: async ({ proposedResult }) => ({ action: "complete", result: proposedResult }),
});
await registration?.dispose();
```
### `@nklisch/pi-subagents/settings` — layered config loader
Extensions that store configuration in JSON files can use the shared layered loader, which reads a global file (`/`) and a project file (`/.pi/`) and merges them — project wins on conflicts, missing files are silent, malformed files warn and fall back:
```typescript
import { loadLayeredSettings, type LayeredSettingsSource } from "@nklisch/pi-subagents/settings";
interface MyConfig { enabled?: boolean; limit?: number }
function sanitize(raw: unknown): Partial {
if (!raw || typeof raw !== "object") return {};
const r = raw as Record;
const out: Partial = {};
if (typeof r.enabled === "boolean") out.enabled = r.enabled;
if (typeof r.limit === "number") out.limit = r.limit;
return out;
}
const config = loadLayeredSettings({
agentDir, // Pi runtime agent home directory
cwd, // project root — project file lives at /.pi/
filename: "my-extension.json",
sanitize,
warnLabel: "my-extension", // prefix for the malformed-file stderr warning
});
```
`loadLayeredSettings` returns `Partial` (all fields optional); apply your defaults after the call.
It never throws — all error conditions produce a `console.warn` and return `{}`.
## Architecture
This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.
See [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) for the full architecture document — design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap.
## Relationship to upstream
This package is a maintained fork of [`@gotgenes/pi-subagents`](https://www.npmjs.com/package/@gotgenes/pi-subagents), itself an independently maintained hard fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
It retains the minimal core and adds only the generic lifecycle-provider seam described above.
The fork follows the rebase, security, and return-to-upstream policy in [Fork maintenance](./docs/FORK-MAINTENANCE.md).
## License
MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)