pi-subagents-lite

Sub-agents for pi. Schema-first, minimal token overhead.

Spawn custom agents in isolated session with own tools, extensions and model. Three tools with one-dot descriptions — the least strict OpenAI-tools gateways accept. Names like Agent, run_in_background, and worktree_path are the schema.

Foreground and background agents with detailed model configuration, concurrency, custom agent types, steering and continuation, cross-repo worktree support, configurable system prompt modes, a live widget and conversation viewer with cost tracking, and a watchdog for stuck agents.

Install

Requires Node.js >= 18 and pi >= 0.82.0.

pi install npm:pi-subagents-lite
pi install -l npm:pi-subagents-lite   # project-local
pi -e npm:pi-subagents-lite           # try without installing

Usage

The LLM calls Agent like any other tool. Foreground agents return inline with stats. Background agents acknowledge immediately and auto-deliver on completion.

◈ Agents
  ⠧ builder  Bump all gpu_inference_proxy deps to latest  6⟳ ·↑7k↓2k 2%·$0.00·54s
  │ MiMo V2.5 • high
  └ running command…
  ⠧ scout  Explore keepalive events config  25⟳ ·↑79k↓5k 8%·$0.01·2m 39s
  │ MiMo V2.5 • high
  └ Now I have enough information to provide a comprehensive answer.

The widget shows running and recently finished agents above the editor. ↓/↑ highlights an agent, Enter opens the conversation viewer, Esc closes navigation. The viewer streams the live transcript — thinking blocks, tool calls, and compaction summaries. Tool results are not shown: each call appears as a single status-colored line (pending → success/error).

The /agents menu covers running agents (view, steer, continue settled agents, stop, clear), manual spawns without an LLM round-trip, model settings, concurrency, and widget layout.

Agent tools

• Agent spawns a sub-agent (see Agent options for parameters).
• StopAgent stops a running or queued agent by ID. IDs come from the spawn result, the stop error, or /agents.
• MessageAgent gives an existing agent more input by ID: a running one picks it up at its next turn boundary, a settled one continues on it with its own context.
• AgentStatus lists all agents with type, short ID, and status.

Both ID forms work as input: the short ID shown in listings resolves when it identifies exactly one agent, and a prefix that matches several is refused rather than guessed.

Foreground agents dont lock the session and can be stopped by parent's interrupt. Background agents are fully autonomous.

Steering and continuation

Steer a running agent mid-task to redirect it: Enter in the conversation viewer, Steer in the /agents menu, or MessageAgent from the session agent. Settled agents (completed, errored, stopped, turn-limited) can be continued from the conversation viewer, the /agents menu, or MessageAgent, as long as their session is still live.

Permission gates and other Subagent-aware extensions

Lite announces each Subagent session on pi's extension event bus when it is created, when its extensions bind, and when it is disposed. A gate installed alongside lite, for example @gotgenes/pi-permission-system, uses those announcements to escalate an ask decision made inside a Subagent to the parent session instead of failing closed inside the child. With no such extension installed nothing is observable, on a pi without the event bus the announcements are skipped, and if pi refuses one, which happens when the parent session is replaced, reloaded or disposed while the Subagent is still running, lite warns and names that Subagent. An announcement never fails a spawn or a teardown.

Built-in agents

• general-purpose does general task execution using the configured session tools.
• Explore does read-only codebase exploration.

Built-ins can be overridden by custom agents or disabled from /agents. Disabling takes effect immediately for future Agent calls. Running and queued agents continue with the policy captured at spawn.

Custom agents

Drop a .md file into .pi/agents/ (project), .agents/agents/ (shared), or ~/.pi/agent/agents/ (global). Frontmatter configures the agent, the body is its system prompt. The name auto-populates the agent parameter's enum, so nothing needs registering. On name clash, project > shared > user > built-in. Type names resolve case-insensitively.

---
name: security-review
description: Review code for security issues
tools: [read, bash, grep]
extensions: false
skills: false
model: zai/glm-5.2
thinking: high
max_turns: 80
---

You are a security review specialist. Analyze code for vulnerabilities,
focusing on injection flaws, auth bypasses, and insecure defaults.

A minimal agent with just name and description gets everything, same as general-purpose. Set restrictions only when you want them.

Frontmatter reference

Field	Type	Default	Description
name	string	—	Agent type name. Must be unique; a file without it is skipped.
display_name	string	name	Label in the UI.
color	string	none	Agent color for icon tinting. Named colors: red, blue, green, yellow, purple, orange, pink, cyan. Palette aliases: amber, teal, indigo, gold, violet, rose, lime, gray, slate, navy, etc. Also accepts #RRGGBB hex.
description	string	""	One-sentence description.
tools	true | string[] | false	true	Tool whitelist. Mutually exclusive with exclude_tools.
exclude_tools	string[]	none	Tool blacklist. Mutually exclusive with tools.
extensions	true | string[] | false	true	Which extensions load (hooks and commands). Does not control tool visibility.
exclude_extensions	string[]	none	Extension blacklist.
skills	true | string[] | false	true	Skill whitelist (metadata-only in system prompt).
preload_skills	string[] | false	false	Dump full SKILL.md content into the system prompt. Expensive.
model	string	inherit parent	"provider/model-id". See Model resolution.
thinking	string	see Thinking level resolution	off, minimal, low, medium, high, xhigh, max, or parent to follow the parent session.
max_turns	number	unlimited	Soft turn limit, then grace turns before hard abort.
max_tokens	number	unlimited	Max output tokens per LLM response.
hidden	boolean	false	Hide from the enum. Still callable by name.
output_transcript	boolean	inherit global	Write streaming transcript to /tmp/pi-agent-outputs/<agentId>.log (frontmatter overrides).
include_context_files	boolean	inherit global	Include AGENTS.md files as <project_context> in the system prompt. true = load, false = none, unset = global "Include AGENTS.md" setting.
include_system_prompt	boolean	inherit global	Include the parent's system prompt for this agent. true = inherit parent, false = replace mode, unset = global mode. When the global mode is custom, the custom prompt wins over true.

When frontmatter omits tools and the agent type carries no explicit registered-tools set, loadToolsImplicitly (config, default ON) decides: ON delegates tool setup to pi, so your defaultTools setting applies exactly as in a normal session, and tools left inactive stay registered for dispatcher tools to call by name. OFF starts such agents with no tools. Explicit frontmatter always wins.

tools and exclude_tools accept built-in names (read, bash, edit, write, grep) and extension tool names (web_search). Use tavily/* or tavily/all in either list to include or exclude all tools from that extension. Excluding tools doesn't prevent the extension from loading; use exclude_extensions: [tavily] to prevent loading.

loadSkillsImplicitly, loadExtensionsImplicitly, and loadToolsImplicitly (config, default ON) decide what an agent gets when frontmatter omits skills, extensions, or the tool fields. Turn one OFF to default new agents to nothing on that axis and opt in explicitly.

Built-in extensions: child sessions load pi's built-in codemode, tool-search, and mcp extensions (llama.cpp excluded), addressed by bare name (codemode) from defaultTools, settings extensions, and frontmatter, exactly as in a normal session. A user extension registering the same tool, command, or flag replaces the built-in.

Codemode in Subagents needs two things: the codemode extension loaded, and the codemode tool activated. With default settings one line does both, in .pi/settings.json:

{ "defaultTools": ["+codemode"] }

Every agent whose frontmatter omits tools then starts with codemode active, exactly like your main session. Agents with an explicit tools list ignore defaultTools: add codemode to that list to activate it. If loadExtensionsImplicitly is off, agents also need extensions: codemode in frontmatter to load the extension.

Agent options

Agent accepts:

• prompt (required) is the task text.
• description is a short label for the widget; defaults to the first line of the prompt.
• agent is the agent type; defaults to general-purpose.
• run_in_background makes the agent return immediately and notify the parent when complete.
• worktree_path is any git repository on disk: a worktree of the parent's repo, its main checkout, or a different repo entirely. See Worktree paths and trust.

model, thinking, max_turns, and max_tokens are injected from config and frontmatter, never passed by the LLM. Set them once and forget.

Subagents cannot spawn further subagents.

Worktree paths and trust

worktree_path accepts a path inside any git repository on disk: a linked worktree of the parent's repo, its main checkout, or a different repo entirely. The subagent runs with that directory as its working directory. A path outside any git repo is rejected.

Cross-repo targets are gated by pi's existing trust framework. The target's saved trust decision (nearest ancestor wins) applies, and an undecided target falls back to the global defaultProjectTrust setting. Anything other than "always" means untrusted. An untrusted target still spawns, but its project resources (.pi/ settings, extensions, skills, prompts, themes, system prompt files, .agents/skills) are ignored, its .pi/agents types are not discovered, the extension's project config (.pi/subagents-lite.json) is not loaded, and pi surfaces a warning. Same-repo paths are never gated. The /agents spawn wizard still lists same-repo worktrees only.

Model resolution

Precedence, highest first:

1. Session per-type override (/agents > Model settings)
2. Session global default
3. Config per-type override (~/.pi/agent/subagents-lite.json)
4. Config global default
5. Agent frontmatter model
6. Parent model

Thinking level resolution

Precedence, highest first:

1. Spawn choice (/agents spawn wizard)
2. Agent frontmatter thinking
3. pi's per-model level for the resolved model (modelThinkingLevels)
4. Subagent default thinking (defaultThinking, project over global)
5. pi's own default (defaultThinkingLevel, else medium)

Then clamped to the resolved model's supported levels; non-reasoning models support only off.

Any source can hold parent to follow the parent session's current level: thinking: parent for one agent type, Subagent default thinking for every Subagent with no higher source. Resolution happens before the Subagent starts, so a run always reports a real level, and a parent with no parent to read counts as unset.

Model settings and the spawn wizard print the deciding source in brackets: high (frontmatter), medium (pi default), minimal (parent). pi default means nothing is configured here, so pi's own setting decides; in the spawn wizard that choice sends no level at all.

Concurrency

concurrency caps parallel agents. A per-model limit overrides a per-provider limit, which overrides the default per-model limit. Excess spawns queue until a slot frees.

Settings

Global settings live in ~/.pi/agent/subagents-lite.json, managed via /agents or edited directly.

/agents covers model settings per-type overrides, concurrency, widget, spawn defaults (Subagent default thinking, max turns, force-background), system prompt mode, watchdog timeouts.

Settings

→ Model                           Set global default and per-type model overrides
  Concurrency                     Set per-model slot limits
  Agent                           Agent limit, colors, output, thinking
  System prompt                   Prompt mode, AGENTS.md, skills, extensions
  Widget                          Configure widget display options

Widget is higly customizable as the rest of the extension

Project-level config

A project can commit its own defaults as .pi/subagents-lite.json (same file name as the global one). This is an override layer, not a full config. It may contain only model and concurrency settings (agent.default, per-type model overrides, concurrency), and each key it sets overrides the global file's value. Every other setting (widget, watchdog, spawn defaults) always comes from the global file. The effective value of each key resolves as: session override > project file > global file > built-in default.

System prompt mode

systemPromptMode (default replace):

• replace uses a minimal generic prompt plus the agent's instructions. Lowest cost and most isolated.
• inherit uses the parent's system prompt plus the agent's instructions.
• custom uses ~/.pi/agent/subagents-lite-prompt.md plus the agent's instructions.

When includeContextFiles is true (default), AGENTS.md files load as shared context before agent instructions, which improves KV cache prefix hits.

Watchdog

The watchdog stops agents that hang. Two independent checks, both default 45 minutes, 0 disables:

• toolTimeoutMinutes: a single tool call running longer than this stops the agent.
• idleTimeoutMinutes: no activity (tool events or streamed response text) for this long stops the agent.

The watchdog notifies the main session on a kill so it can act accordingly.

Output transcripts

Output transcripts are disabled by default. Enable them globally via the outputTranscript config option or per-agent via the output_transcript frontmatter field. When enabled, the transcript streams to /tmp/pi-agent-outputs/<agentId>.log (append-only, tail -f friendly) and the widget shows the tail -f line. Logs and completed results survive on disk even if a session reload (/reload, extension reload) kills running agents.

License

MIT