pi-subagents-lite

Sub-agents for pi — schema-first, zero-fluff.

Spawn specialized agents with isolated sessions, custom tools, and per-type models at minimal token cost.

Schema-First Design

Every tool the LLM sees costs tokens — in the system prompt and in every turn. Most extensions layer on descriptions, prompt snippets, and usage guidelines that compound across the session. This extension takes a schema-first approach: the tool name and parameter names are the schema. No bloated descriptions, no prose.

Standard	Schema-first
description: "Spawn a sub-agent"	(removed)
promptSnippet with usage examples	(none)
promptGuidelines with rules	(none)
Parameters with .description()	Bare Type.String()

Names like Agent, StopAgent, AgentStatus, run_in_background, worktree_path are self-documenting. Results reinforce correct usage with clear success/error messages.

Result: foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides, and agent status — all with minimal token overhead.

Features

• Three tools — Agent (spawn), StopAgent (stop), AgentStatus (list)
• Foreground & background — block, or fire-and-forget with auto-delivered results
• Custom agent types — .md files with YAML frontmatter (tools, model, thinking, turn/token limits)
• Manual spawn — from /agents, no LLM round-trip; full control over model, thinking, turns, tokens, background
• Model resolution — 6-level precedence chain; set once, forget
• Concurrency — per-model and per-provider slot limits with automatic queuing
• Steering — inject mid-execution guidance into running agents
• Cost & usage tracking — input/output/cache tokens and dollar cost per agent (toggle in stats)
• Live widget — persistent status bar with running/completed agents, full and compact modes
• Result viewer — fullscreen markdown with stats
• Worktrees — run agents in a git worktree via worktree_path
• Output logs — tail -f friendly, ISO-timestamped

Install

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

Quick Start

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

Running agents appear in the live widget:

● Agents
├─ ⠙ Agent  Write model precedence unit tests  6🛠 ·3⟳ ·↑6.8k↓1.3k 6%·12s
│  │ tail -f /tmp/pi-agent-outputs/bb3382a9-1f7e-474.log
│  └ The file already exists but is ~175 lines. The user wants a …
├─ ⠙ Agent  Code review of agent-runner.ts  4🛠 ·2⟳ ·↑7.2k↓1.5k 4%·12s
│  └ Now let me check the types and related files for context on …
└─ ⠙ Explore  Explore codebase architecture  13🛠 ·4⟳ ·↑16.1k↓2.9k 15%·12s
   └ ## Architecture Summary: pi-subagents-lite

Background agents deliver a result notification when done:

 Subagent Result

 ✓ Explore (model-name)·13🛠 ·5⟳ ·↑25.9k↓4.9k 15%·21s
   Explore codebase architecture
   tail -f /tmp/pi-agent-outputs/4f6b0f08-7a9a-419.log

Foreground results land inline:

 ▸ Explore
 ✓ 31🛠 ·6⟳ ·↑48.1k↓9.2k 28%·39s
   Explore project directory structure

Stop a running agent from /agents:

○ Agents
└─ ■ Agent  Code review of agent-runner.ts  12🛠 ·10⟳ ·↑32.8k↓6.2k 8%·52s stopped
    tail -f /tmp/pi-agent-outputs/23689696-3cd3-400.log

Tools

Agent

Spawn a sub-agent.

Parameter	Required	Description
prompt	✅	The task for the sub-agent
description		Brief description for the caller (optional — derived from prompt if omitted)
agent		Type name — general-purpose, Explore, or any custom type. Auto-populated from .md files in your agent directories; drop a file, it appears in the enum. hidden: true hides a type from the list (still callable by name).
run_in_background		Fire-and-forget; result delivered automatically when done
worktree_path		Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its .pi/agents/, and shows a worktree label in the UI. Validated against the parent repo's git common dir.

model, max_turns, max_tokens, and thinking are not visible to the LLM — injected at call time from agent config and frontmatter. See Custom Agent Types.

StopAgent

Stop a running agent by ID.

Parameter	Required	Description
agent_id	✅	The agent ID returned by Agent at spawn

IDs come from the Agent result, the StopAgent error (lists all running IDs), or /agents → Running agents.

AgentStatus

List all agents with type, short ID, and status. Output: type·short_id·status, ... (e.g. general-purpose·a1b2c3·running, Explore·d4e5f6·completed).

The result nudges the LLM to wait for automatic notifications instead of polling — preventing wasteful repeated calls while still letting it discover agents when needed.

Custom Agent Types

Drop a .md file into .pi/agents/ (project) or ~/.pi/agent/agents/ (global). Frontmatter configures the agent; the body is its system prompt. The name field (or filename) becomes the agent type and auto-populates the agent parameter's enum — no registration. Files added mid-session are picked up on the next call that references them.

Built-ins general-purpose and Explore are always available. Project agents override user agents, which override built-ins.

---
name: security-review
display_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 — just name and description — gets everything: all tools, extensions, and skills, same as general-purpose. Set restrictions only when you want them.

Frontmatter reference

Field	Type	Default	Description
name	string	filename	Agent type name (the agent enum value). Must be unique.
display_name	string	name	Label in the widget, /agents menu, and result viewer.
description	string	""	One-sentence description in the /agents list and tool rendering.
tools	true | string[] | false	true	Tool whitelist — which tool schemas the LLM sees. Accepts built-in names and extension tool references (see below). Mutually exclusive with exclude_tools.
exclude_tools	string[]	none	Tool blacklist — all tools except these are visible. Supports ext/* syntax. Mutually exclusive with tools (when tools is string[]).
extensions	true | string[] | false	true	Extension loader — which extensions load (hooks + commands fire). Does NOT control tool visibility. Mutually exclusive with exclude_extensions.
exclude_extensions	string[]	none	Extension blacklist — all extensions except these load. Mutually exclusive with extensions (when extensions is string[]).
skills	true | string[] | false	true	Skill whitelist — which skills are available (metadata in system prompt).
preload_skills	string[] | false	false	Full skill injection — dump complete SKILL.md content into the system prompt instead of metadata-only.
model	string	inherit parent	Default model as "provider/model-id". See Model Resolution.
thinking	string	inherit parent	One of: off, minimal, low, medium, high, xhigh.
max_turns	number	unlimited	Soft turn limit. Agent gets a steer at the limit, then max_turns + graceTurns before hard abort.
max_tokens	number	unlimited	Max output tokens per LLM response. Injected into provider request payloads.
hidden	true | false	false	true hides the type from the enum (LLM can't see or invoke it). Still callable by name.

Tool control (tools / exclude_tools)

Use a whitelist (tools) when an agent needs few tools, or a blacklist (exclude_tools) when it needs most. You can use either, not both; if both are set, the whitelist wins.

Built-in tool names: read, bash, edit, write, grep.

Value	Meaning
true / omitted	All tools visible
false	No tools visible
[read, bash]	Only listed built-in tools
[web_search]	Extension tool by name
[tavily/*]	All tools from an extension
[tavily/web_search]	Specific tool from an extension

# Read-only via whitelist
tools: [read, bash, grep]
extensions: false

# Same result via blacklist (easier to maintain as the toolset grows)
exclude_tools: [edit, write]

exclude_tools: [tavily/*] hides tavily's tools but the extension still loads (hooks fire). Use exclude_extensions: [tavily] to prevent loading entirely.

Extensions & skills

What they are:

• Tools are callable functions — read, bash, edit, write, grep (built-in), or web_search / tavily/* (from extensions). The tools whitelist controls which tool schemas the LLM sees.
• Skills are reusable instruction files (SKILL.md) that teach an agent how to do a task — e.g. debug, tdd. By default the agent sees only skill metadata (name, description, path) in its system prompt and reads the full content on-demand via read.
• Extensions are pi plugins (e.g. tavily, pi-tokf) that register tools and hooks. Loading one makes its hooks fire and its tools available — but those tools still need to pass the tools whitelist to be visible.

extensions controls which extensions load (hooks + tool registration), not tool visibility. skills and preload_skills control skill availability. Same whitelist/blacklist rules and ext/* syntax as tools.

extensions value	Meaning
true / omitted	Load all extensions
false	Load none
[tavily, pi-tokf]	Load only listed extensions

Skill field	Value	Effect
skills	true / [debug, tdd] / false	All / listed / no skills (metadata-only in system prompt)
preload_skills	[debug] / false	Dump full SKILL.md content / none (default)

Implicit loading. loadSkillsImplicitly and loadExtensionsImplicitly are config globals that decide what an agent gets when its frontmatter omits skills / extensions. They default ON, so an agent that says nothing about either gets everything. Turn them OFF (in config, or /agents → System prompt) to default every new agent to nothing — isolated sessions and minimal token cost, with agents opting in explicitly via skills: [debug] / extensions: [tavily]. A concrete frontmatter value always overrides the global.

Token cost ranking (highest → lowest): preload_skills ≫ tools/exclude_tools (each tool schema every turn) > extensions (hooks fire every turn) > skills (metadata-only, agent reads full content on-demand) > skills: false (zero). Prefer metadata skills over preloading; whitelist tools aggressively for narrow agents.

Model Resolution

The extension picks the right model automatically. Precedence (highest first):

1. Session per-type override — /agents → Model settings, lasts the session
2. Session global default — temporary
3. Config per-type override — ~/.pi/agent/subagents-lite.json
4. Config global default
5. Agent frontmatter — model in .md
6. Parent model — inherit from the calling agent

The LLM never passes model — it's injected at call time. Set it once in config or frontmatter and forget.

System Prompt Mode

Control how the subagent system prompt is built via systemPromptMode (default: replace):

• replace — minimal generic prompt plus the agent's own <agent_instructions>. Lowest token cost, most isolated.
• inherit — parent's system prompt (scaffolding stripped to avoid duplication) plus <agent_instructions>. Best when agents need parent context and guidelines.
• custom — content of ~/.pi/agent/subagents-lite-prompt.md plus <agent_instructions>. Full control.

When includeContextFiles is true (default), AGENTS.md files from the project root and ~/.pi/agent/ load as <project_context> before agent-specific instructions — shared static context improves KV cache prefix hit rates. Toggle off to cut token cost.

Commands

/agents

Management menu with four sections:

• Running agents — status and description; per-agent actions (view snapshot, result, error; steer; stop) and bulk stop
• Spawn agent — manually spawn without the LLM. Pick a type, enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
• Settings
  • Model settings — global default, per-type overrides, session overrides, clear all
  • Spawn options — force background, grace turns, default max turns, default thinking, disable default agents
  • System prompt — mode, custom prompt file, include AGENTS.md, load skills/extensions implicitly
  • Concurrency — default limit, per-provider and per-model slots, reset to defaults
  • Widget settings — force compact, max lines, description length, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)

Interface

Live widget

Persistent bar above the editor showing running and completed agents, updating live. Running agents show a spinner, current tool activity, turn count, token usage (with optional context-fill %), and elapsed time. Completed agents show a check mark with final stats. Click the tail -f path to follow output logs.

Full mode (tree, header + tail -f path + activity):

├─ ⠙ Explore  description  3🛠 ·5≤30⟳ ·↑10.2k↓1.8k 45%·1h 2m 3s
│  │ tail -f /tmp/pi-agent-outputs/...
│  └ thinking…

Compact mode (single line, description truncated, activity inline):

├─ ⠙ Explore  description trunc…  3🛠 ·5≤30⟳ ·↑10.2k↓1.8k 45%·1h 2m 3s  thinking…

Turn format uses ≤ and ⟳ (5≤30⟳ = 5 of 30 turns). Turn count is colored by usage: normal < 80%, warning 80–99%, error at 100%. The max is hidden when well below the limit. Token glyphs (↑ input, ↓ output) are self-explanatory — no "tokens" label.

Compact mode is active when Force compact is ON, or ctrl+o shortcut is ON and the user has collapsed tool expansion. Force compact always wins.

Result viewer

Fullscreen markdown viewer for completed agent results — opens automatically from /agents. Keys: ↑↓ / PgUp/PgDn navigate · g/G top/bottom · f fullscreen · r refresh · q/Esc close. Stats line: ↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s.

With Cost display ON, stats show dollar cost (✓ Builder·2🛠 ·5⟳ ·↑10.2k↓1.8k $0.008·10s) and the status bar totals it (agents: $0.008). Toggle as a session override from Model settings.

Configuration

~/.pi/agent/subagents-lite.json — managed via /agents, or edit directly. Per-type model overrides (e.g. "Explore") are dynamic keys alongside the special fields.

{
  "agent": {
    "default": "zai/glm-5.2",
    "forceBackground": true,
    "graceTurns": 6,
    "showCost": true,
    "showTools": false,
    "showTurns": true,
    "showInput": true,
    "showOutput": true,
    "showContext": true,
    "showTime": true,
    "widgetMaxLines": 12,
    "widgetMaxLinesCompact": 6,
    "widgetDescLengthFull": 50,
    "widgetCompact": true,
    "widgetShortcut": false,
    "systemPromptMode": "inherit",
    "includeContextFiles": true,
    "loadSkillsImplicitly": false,
    "loadExtensionsImplicitly": false,
    "disableDefaultAgents": false,
    "Explore": "xiaomi/mimo-v2.5",
    "builder": "xiaomi/mimo-v2-pro",
    "architecture-reviewer": "zai/glm-5.2",
    "planner": "zai/glm-5.2"
  },
  "concurrency": {
    "default": 4,
    "providers": {
      "llamacpp": 1,
      "ai.lan": 2
    },
    "models": {}
  }
}

Widget settings

Field	Default	Description
widgetMaxLines	12	Max body lines in full mode (excluding heading).
widgetMaxLinesCompact	half of widgetMaxLines	Max body lines in compact mode.
widgetDescLengthFull	50	Max description length in full mode.
widgetDescLengthCompact	30	Max description length in compact mode.
widgetCompact	false	Force compact mode regardless of ctrl+o state.
widgetShortcut	false	When ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact is manual via widgetCompact.

Stats visibility

Field	Default	Description
showTools	true	Tool count (🛠).
showTurns	true	Turn count (⟳).
showInput	true	Input tokens (↑).
showOutput	true	Output tokens (↓).
showContext	true	Context-fill percent (%).
showCost	false	Dollar cost ($).
showTime	true	Elapsed time.

Reload safety: if a session reload (/reload, extension reload) kills running agents, the UI reports the count lost. Output logs and completed results are preserved on disk.

Output Logs

/tmp/pi-agent-outputs/<agentId>.log — append-only, human-readable, tail -f friendly. Every line is ISO-8601 timestamped:

2026-05-27T12:00:00.000Z [USER] Find all authentication files
2026-05-27T12:00:02.000Z [TOOL] read("src/auth/index.ts")
2026-05-27T12:00:02.000Z [TOOL_RESULT] read: 234 chars
2026-05-27T12:00:15.000Z [ASSISTANT] I found the authentication module...
2026-05-27T12:00:45.000Z [DONE] 5 turns, 12 tool uses, 12.3k tokens, $0.024

Requirements

• Node.js >= 18
• pi >= 0.74.0

License

MIT