leocavalcante/pi-subagents

A Pi extension that delegates tasks to separate Pi processes with isolated context windows.
Extracted from Leo Cavalcante's dotfiles and based on the subagent example bundled with Pi 1.0.0. Adds session-owned background execution.
Contents
- Quick start
- Installation
- Agent definitions
- Usage
- Filter by capability tag
- Filter by multiple capability tags
- Dispatch using capability tags
- Named chain outputs
- Model and thinking overrides
- Tool allowlist overrides
- Inherited environment filtering
- Batch concurrency
- Task deadlines
- Background execution
- Wait for a background job
- Read captured job output
- Usage accounting
- Output capture and cleanup
- Security
- Contributing
- Origin and license
Quick start
Install the published npm package and reload Pi:
If Pi is already running, enter /reload so it loads the newly installed extension.
Create the personal agent directory if it does not already exist. On macOS/Linux, run:
In Windows PowerShell, run:
Then save a personal agent definition as ~/.pi/agent/agents/reviewer.md:
Then ask Pi to delegate a task:
See Installation for local installs and Windows setup, and Agent definitions for project agents and optional settings.
Installation
Requires Pi and Node.js 22.19.0 or newer. Tested with Pi 1.0.4 and 1.1.0 paired with Pi Codemode 1.1.0, and with Pi 1.2.0. Fresh installs of Pi 1.0.4 or 1.1.0 may resolve incompatible Pi Codemode 1.2.0; see the upstream bug report. To install an older Pi with its compatible Codemode version, run the matching command:
Alternatively, use Pi 1.2.0. Pi provides the runtime dependencies, so no build step is needed.
The npm package is published as version 0.2.0. Install that version with:
To install unreleased changes from the current GitHub main branch instead, use:
From the checkout root, install the local copy with:
Run /reload in Pi after installation. Remove any previous copy or symlink at ~/.pi/agent/extensions/subagent before installing the package to avoid registering the tool twice.
For development without changing Pi settings, symlink the checkout instead:
Run that command from the checkout, with no existing subagent directory. Use either a package install or the symlink, not both. On Windows, use PowerShell and a directory junction instead of the POSIX ln -s command:
Run this from the checkout root. A junction avoids requiring Windows symbolic-link privileges; remove it with Remove-Item (Join-Path $HOME ".pi\agent\extensions\subagent") when you no longer need the local install.
Agent definitions
Keep personal agent definitions in ~/.pi/agent/agents/*.md. They are not bundled with this package.
An agent can set model, thinking, tools, optional discovery tags, a default timeoutMs, a default working directory with cwd, and inherited environment variables to remove with unsetEnv in its frontmatter. Agent cwd paths resolve relative to the parent session's working directory, not the definition file. Model selectors are limited to 512 UTF-8 bytes and reject control characters so they remain safe to pass as child-process arguments:
Tags are ASCII slugs using letters, digits, dots, underscores, or hyphens, beginning with a letter or digit; input is normalized to lowercase. Tags are discovery labels, limited to 32 labels of at most 64 bytes each and 2 KiB total, and searchable with subagent_agents. Dispatch can also use them to select an agent with agentTags; this does not change the agent's execution settings.
An agent with no model configured—or with an empty or whitespace-only model value—inherits the parent's active model and thinking level. An explicit thinking overrides the inherited level or the level in a model suffix. Valid levels are off, minimal, low, medium, high, xhigh, and max; Pi clamps them to the model's capabilities.
Without tools, it uses Pi's defaults. Both tools: read, bash and tools: [read, bash] work. Set tools: [] to disable the initial tool selection. Entries cannot contain commas or control characters because the child CLI parses a comma-separated list; they also cannot start with + or -, which Pi interprets as modifiers to the default tool selection rather than allowlist names. Tool arrays are limited to 256 entries; comma-separated values and the normalized --tools argument are each capped at 4 KiB of UTF-8 text. This is not a sandbox; extensions can still change the selection.
Definitions need non-empty name and description fields. Agent timeoutMs defaults must be whole milliseconds from 1 to 86400000 (24 hours); call-level values can override or explicitly disable a definition's deadline. Agent cwd defaults must be non-empty, well-formed Unicode paths with no NUL characters and at most 32,767 UTF-16 code units; dispatch paths can override them. A configured working directory is a convenience, not a filesystem sandbox, and does not restrict access to other paths. Agent unsetEnv defaults list portable environment-variable names, with at most 128 names and 4 KiB total; calls and task entries can add more names to remove but cannot restore variables removed by the agent. PI_SUBAGENTS_NESTING_DEPTH is reserved for the recursion limit and cannot be removed. Agent definition files must be valid UTF-8, and metadata escapes that produce unpaired UTF-16 surrogates are rejected rather than silently normalized. Agent names are limited to 256 UTF-8 bytes and cannot contain terminal or bidirectional formatting controls; this keeps identifiers safe in trust prompts, diagnostics, and UI output. Descriptions are limited to 1 KiB of UTF-8 text so listing metadata remains compact. Untrusted metadata shown in listings and project-agent confirmations escapes default-ignorable Unicode code points for display while preserving zero-width joiners, non-joiners, variation selectors attached to emoji or ideographic bases, and registered emoji tag flag sequences; structured metadata remains unchanged. Invalid YAML or configuration skips that definition instead of breaking discovery for all agents. Duplicate names in the same directory produce a diagnostic naming both files. The last valid definition in locale-independent lexical filename order still wins. Intentional project-over-personal overrides do not produce a duplicate warning.