@tintinweb/pi-subagents
Advanced tools
A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.
A pi extension that brings Claude Code-style autonomous sub-agents to pi. 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.
Status: Early release.
https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
Agent, get_subagent_result, steer_subagent) — feels native/agents to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause).pi/agents/<name>.md with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions"explore", "Explore", "EXPLORE" all work. Unknown types fall back to general-purpose with a note"haiku", "sonnet") instead of full IDs, with automatic filtering to only available/configured models.pi/skills/, .agents/skills/, and global locations (Pi-standard <name>/SKILL.md directory layout supported)disallowed_tools frontmattersubagents:created, started, completed, failed, steered, compacted) emitted via pi.events, enabling other extensions to react to sub-agent activitypi.events event bus (subagents:rpc:ping, subagents:rpc:spawn, subagents:rpc:stop). Standardized reply envelopes with protocol versioning. Emits subagents:ready on loadschedule to the Agent tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same subagent-notification followUp path as manual background completions; manage via /agents → Scheduled jobsenabledModels allowlist (sourced from /scoped-models, with both global and project-local pi settings honored). Caller-supplied out-of-scope → hard error to orchestrator; frontmatter-pinned out-of-scope → warning + runs anyway (frontmatter authoritative). Toggle via /agents → Settings → Scope modelspi install npm:@tintinweb/pi-subagents
Or load directly for development:
pi -e ./src/index.ts
The parent agent spawns sub-agents using the Agent tool:
Agent({
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.
Add a schedule field to register the agent to fire later instead of running now:
Agent({
subagent_type: "Explore",
prompt: "Look at recent commits and summarize what changed since last week",
description: "Weekly commit review",
schedule: "0 0 9 * * 1", // 9am every Monday (6-field cron)
})
Schedule formats:
second minute hour day-of-month month day-of-week), e.g. "0 0 9 * * 1" for 9am every Monday, "0 */15 * * * *" for every 15 minutes."5m", "1h", "30s", "2d". Fires repeatedly at that interval."+10m", "+2h", "+1d". Fires once at that future time."2026-12-25T09:00:00.000Z".When a schedule fires, the spawn runs in background and its completion notification arrives in the conversation through the same subagent-notification followUp path as a manually-spawned background agent — your parent agent reasons about the result the same way.
Schedules are session-scoped: they reset on /new and restore on /resume. List and cancel via /agents → Scheduled jobs (creation is the Agent tool's job — there is no parallel manual-create wizard). Storage at <cwd>/.pi/subagent-schedules/<sessionId>.json with PID-based file locking for cross-instance safety.
Disable the feature entirely: /agents → Settings → Scheduling → disabled removes schedule from the Agent tool spec (no LLM-context cost), hides the menu entry, and stops any active scheduler. The schema-level removal takes effect on the next pi session; the runtime kill is immediate. Re-enable from the same menu.
Restrictions:
schedule cannot be combined with inherit_context (no parent conversation exists at fire time) or resume (schedules create fresh agents).run_in_background is forced to true.maxConcurrent queue so a 5-minute interval cannot be deferred behind long-running manual agents.pi -p doesn't wait for scheduled subagents.The extension renders a persistent widget above the editor showing all active agents:
● 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 Claude Code-style 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:
✓ 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
Group completions render each agent as a separate block. The LLM receives structured <task-notification> XML for parsing, while the user sees the themed visual.
| 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 (standalone) | Fast codebase exploration (read-only) |
Plan | read, bash, grep, find, ls | inherit | replace (standalone) | Software architect for implementation planning (read-only) |
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 and Plan use standalone prompts tailored to their read-only roles.
Default agents can be ejected (/agents → select agent → Eject) to export them as .md files for customization, 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.
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 two locations (higher priority wins):
| Priority | Location | Scope |
|---|---|---|
| 1 (highest) | .pi/agents/<name>.md | Project — per-repo agents |
| 2 | $PI_CODING_AGENT_DIR/agents/<name>.md (default ~/.pi/agent/agents/<name>.md) | Global — available everywhere |
Project-level agents override global ones with the same name, so you can customize a global agent for a specific project. 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.
.pi/agents/auditor.md---
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:
Agent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
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 for no tools |
extensions | true | Inherit MCP/extension tools. false to disable |
skills | true | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see Skill Preloading for discovery locations) |
memory | — | Persistent agent memory scope: project, local, or user. Auto-detects read-only agents |
disallowed_tools | — | Comma-separated tools to deny even if extensions provide them |
isolation | — | Set to worktree to run in an isolated git worktree |
model | inherit parent | Model — provider/modelId or fuzzy name ("haiku", "sonnet") |
thinking | inherit | off, minimal, low, medium, high, xhigh |
max_turns | unlimited | Max agentic turns before graceful shutdown. 0 or omit for unlimited |
prompt_mode | replace | replace: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). append: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
inherit_context | false | Fork parent conversation into agent |
run_in_background | false | Run in background by default |
isolated | false | No extension/MCP tools, only built-in |
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, run_in_background, isolated, or isolation, those values are locked for that agent. Agent tool parameters only fill fields the agent config leaves unspecified.
AgentLaunch 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_turns | number | no | Max agentic turns. Omit for unlimited (default) |
run_in_background | boolean | no | Run without blocking |
resume | string | no | Agent ID to resume a previous session |
isolated | boolean | no | No extension/MCP tools |
isolation | "worktree" | no | Run in an isolated git worktree |
inherit_context | boolean | no | Fork parent conversation into agent |
get_subagent_resultCheck status and retrieve results from a background agent.
| 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_subagentSend 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 |
| Command | Description |
|---|---|
/agents | Interactive agent management menu |
The /agents command opens an interactive menu:
Running agents (2) — 1 running, 1 done ← only shown when agents exist
Agent types (6) ← unified list: defaults + custom
Create new agent ← manual wizard or AI-generated
Settings ← max concurrency, max turns, grace turns, join mode
• (project), ◦ (global), ✕ (disabled). Select an agent to manage it:
.md), Disable.md file to project or personal location, so you can customize it✕) and can be re-enabled.md file). Any name is allowed, including default agent names (overrides them)Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
max_turns — steering message: "Wrap up immediately — provide your final answer now."| 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 |
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 queued agents as a collapsed count.
Foreground agents bypass the queue — they block the parent anyway.
When background agents complete, they notify the main agent. The join mode controls how these notifications are delivered. It applies only to background agents.
| Mode | Behavior |
|---|---|
smart (default) | 2+ background agents spawned in the same turn are auto-grouped into a single consolidated notification. Solo agents notify individually. |
async | Each agent sends its own notification on completion (original behavior). Best when results need incremental processing. |
group | Force grouping even when spawning a single agent. Useful when you know more agents will follow. |
Timeout behavior: When agents are grouped, a 30-second timeout starts after the first agent completes. If not all agents finish in time, a partial notification is sent with completed results and remaining agents continue with a shorter 15-second re-batch window for stragglers.
Configuration:
/agents → Settings → Join modeOpt-in: off by default. Enable via /agents → Settings → Scope models.
When on, each subagent spawn's effective model is validated against pi's own enabledModels list (configured via pi's /scoped-models UI). pi-subagents reads that list; it doesn't manage it. Both of pi's settings files are honored: global ~/.pi/agent/settings.json and project-local <cwd>/.pi/settings.json. Project overrides global — mirrors pi's SettingsManager deep-merge, so a tighter per-project scope (hand-edited into the project settings) is respected.
Out-of-scope handling depends on source:
| Model source | Out-of-scope behavior |
|---|---|
Caller-supplied via Agent({ model: "..." }) | Hard error returned to the orchestrator, listing allowed models |
| Pinned in agent frontmatter | Warning toast + the pinned model runs (frontmatter is authoritative) |
| Parent-inherited (neither set) | Warning toast + parent's model runs |
Design: scopeModels is a guardrail against the orchestrator picking unexpected models at runtime, not a hard policy against user-level config. The "frontmatter is authoritative" guarantee from v0.5.1 still holds for model: — caller params can't override frontmatter, and frontmatter pins run even when out of scope (with a visible warning).
Pattern format: only exact provider/modelId entries are honored (e.g. anthropic/claude-haiku-4-5-20251001). Glob patterns (*sonnet*), bare model IDs, and :thinking suffixes — which pi itself supports — are silently dropped here. pi's /scoped-models picker writes exact entries, so the limitation is invisible if you configure scope through the UI. Hand-edited globs produce an empty allowed set (scope check becomes a no-op).
No-op safety: if enabledModels is missing or empty in pi's settings, scope check skips entirely — no false positives, no spurious errors.
Runtime tuning values set via /agents → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off) persist across pi restarts. Two files, merged on load:
~/.pi/agent/subagents.json — your machine-wide defaults. Edit by hand; the /agents menu never writes here.<cwd>/.pi/subagents.json — per-project overrides. Written by /agents → Settings.Precedence: project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency 4, default max turns unlimited, grace turns 5, join mode smart).
Example — global defaults for a beefy machine:
mkdir -p ~/.pi/agent
cat > ~/.pi/agent/subagents.json <<'EOF'
{
"maxConcurrent": 16,
"graceTurns": 10
}
EOF
Every project now starts with concurrency 16 and grace 10, without ever touching the menu. Individual projects can still override via /agents → 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 /agents toast to a warning with (session only; failed to persist).
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: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:scheduled | Schedule lifecycle change | { type: "added" | "removed" | "updated" | "fired" | "error", … } (job/agentId/error fields per type) |
subagents:scheduler_ready | Scheduler bound to session, enabled jobs armed | sessionId, jobCount |
subagents:ready | Extension loaded and RPC handlers registered | — |
subagents:settings_loaded | Persisted settings applied at extension init | settings (merged global + project) |
subagents:settings_changed | /agents → 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.
Other pi extensions can spawn and stop subagents programmatically via the pi.events event bus, without importing this package directly.
All RPC replies use a standardized envelope: { success: true, data?: T } on success, { success: false, error: string } on failure.
Listen for subagents:ready to know when RPC handlers are available:
pi.events.on("subagents:ready", () => {
// RPC handlers are registered — safe to call ping/spawn/stop
});
Check if the subagents extension is loaded and get the protocol version:
const requestId = crypto.randomUUID();
const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
unsub();
if (reply.success) console.log("Protocol version:", reply.data.version);
});
pi.events.emit("subagents:rpc:ping", { requestId });
Spawn a subagent and receive its ID:
const requestId = crypto.randomUUID();
const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
unsub();
if (!reply.success) {
console.error("Spawn failed:", reply.error);
} else {
console.log("Agent ID:", reply.data.id);
}
});
pi.events.emit("subagents:rpc:spawn", {
requestId,
type: "general-purpose",
prompt: "Do something useful",
options: { description: "My task", run_in_background: true },
});
options.model accepts either a Model object (e.g. ctx.model) or a "provider/modelId" string — strings are resolved against ctx.modelRegistry at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
Stop a running agent by ID:
const requestId = crypto.randomUUID();
const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
unsub();
if (!reply.success) console.error("Stop failed:", reply.error);
});
pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
Reply channels are scoped per requestId, so concurrent requests don't interfere.
Agents can have persistent memory across sessions. Set memory in frontmatter to enable:
---
memory: project # project | local | user
---
| Scope | Location | Use case |
|---|---|---|
project | .pi/agent-memory/<name>/ | Shared across the team (committed) |
local | .pi/agent-memory-local/<name>/ | Machine-specific (gitignored) |
user | ~/.pi/agent-memory/<name>/ | Global personal memory |
Memory uses a MEMORY.md index file and individual memory files with frontmatter. Agents with write tools get full read-write access. Read-only agents (no write/edit tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them. This prevents unintended tool escalation.
The disallowed_tools field is respected when determining write capability — an agent with tools: write + disallowed_tools: write correctly gets read-only memory.
Set isolation: worktree to run an agent in a temporary git worktree:
Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
The agent gets a full, isolated copy of the repository. On completion:
pi-agent-<id>) and returned in the resultIf the worktree cannot be created (not a git repo, no commits, or git worktree add fails), the Agent tool returns a clear error instead of running unisolated — isolation: "worktree" is a strict guarantee, not a hint. Initialize git and commit at least once, or omit isolation.
Skills can be preloaded by name and injected into the agent's system prompt:
---
skills: api-conventions, error-handling
---
Discovery roots (checked in this order, first match wins):
| Scope | Path | Source |
|---|---|---|
| Project | <cwd>/.pi/skills/ | Pi-standard |
| Project | <cwd>/.agents/skills/ | Agent Skills spec |
| User | $PI_CODING_AGENT_DIR/skills/ (default ~/.pi/agent/skills/) | Pi-standard |
| User | ~/.agents/skills/ | Agent Skills spec |
| User | ~/.pi/skills/ | Legacy (pre-Pi) |
Per root, a skill named foo resolves to the first of:
<root>/foo.md — flat file at the top level<root>/foo/SKILL.md — directory skill (top-level)<root>/*/.../foo/SKILL.md — directory skill, found by recursive descentRecursion skips dotfile directories and node_modules. A directory that itself contains a SKILL.md is treated as a single skill — we don't descend into it. Traversal is byte-order sorted for deterministic resolution across filesystems.
Security: symlinks are rejected at every layer (root, flat file, skill directory, SKILL.md inside a skill directory) — intentional deviation from Pi, which follows symlinks. Skill names with path-traversal characters (.., /, \, spaces, leading dot, >128 chars) are rejected.
Block specific tools from an agent even if extensions provide them:
---
tools: read, bash, grep, write
disallowed_tools: write, edit
---
This is useful for creating agents that inherit extension tools but should not have write access.
src/
index.ts # Extension entry: tool/command registration, rendering
types.ts # Type definitions (AgentConfig, AgentRecord, etc.)
default-agents.ts # Embedded default agent configs (general-purpose, Explore, Plan)
agent-types.ts # Unified agent registry (defaults + user), tool name resolution
agent-runner.ts # Session creation, execution, graceful max_turns, steer/resume
agent-manager.ts # Agent lifecycle, concurrency queue, completion notifications
cross-extension-rpc.ts # RPC handlers for cross-extension spawn/ping via pi.events
group-join.ts # Group join manager: batched completion notifications with timeout
custom-agents.ts # Load user-defined agents from .pi/agents/*.md
memory.ts # Persistent agent memory (resolve, read, build prompt blocks)
skill-loader.ts # Preload skills (Pi-standard + Agent Skills spec layouts)
output-file.ts # Streaming output file transcripts for agent sessions
worktree.ts # Git worktree isolation (create, cleanup, prune)
prompts.ts # Config-driven system prompt builder
context.ts # Parent conversation context for inherit_context
env.ts # Environment detection (git, platform)
ui/
agent-widget.ts # Persistent widget: spinners, activity, status icons, theming
conversation-viewer.ts # Live conversation overlay for viewing agent sessions
MIT — tintinweb
FAQs
A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.
The npm package @tintinweb/pi-subagents receives a total of 2,631 weekly downloads. As such, @tintinweb/pi-subagents popularity was classified as popular.
We found that @tintinweb/pi-subagents demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.