Pi Subagent

English | 简体中文

Give Pi reusable specialists for code review, research, and other focused tasks. Each specialist runs in its own Herdr tab and reports back to your main conversation, without inheriting its chat history.

A profile defines a specialist's instructions, tools, and optional skills or model. You can invoke it yourself or let your main Pi delegate work to it.

Install

You need Node.js 22.19+, Pi 1.2.0+, and Herdr. To launch specialists, run Pi inside a Herdr workspace with the herdr command available.

pi install npm:@oldflag2333333/pi-subagent

Restart Pi or run /reload. Pi Subagent uses your existing Pi provider credentials; make sure Pi can already run a normal conversation.

To update later:

pi update npm:@oldflag2333333/pi-subagent

Restart Pi or run /reload after updating.

Try it: a code reviewer

Pi Subagent ships without built-in profiles. Create your first one:

mkdir -p ~/.pi/agent/subagent/profiles/reviewer

Save this as ~/.pi/agent/subagent/profiles/reviewer/config.json:

{
  "version": 1,
  "name": "reviewer",
  "description": "Review code for bugs and missing tests without modifying files.",
  "tools": ["read", "grep", "find", "ls"]
}

Save this beside it as instructions.md:

Review the requested code for bugs, regressions, and missing tests.
Do not modify files. Report actionable findings with file paths and
line numbers. If nothing stands out, say so and note any testing gaps.

In Pi, run /reload, then:

/sub:reviewer Review the authentication code in src/auth.

Replace src/auth with a path in your project. The reviewer opens in a separate Herdr tab and sends its findings back to your main conversation. You can keep working while it runs.

Or ask your main Pi to delegate:

Ask the reviewer profile to review src/auth for bugs and missing tests.

Everyday use

Within the same Main session, repeated /sub:reviewer commands reuse that profile's open Sub. If it is busy, your next task is queued. Finishing a task does not automatically close the tab. Subs can report progress through talk without stopping; endTurn: true explicitly ends their current turn when finished or waiting for Main.

The Sub-agents list shows only assistants created by the current Main: all Open Subs (including idle or unknown status) and Resumable persistent sessions confirmed closed with saved files still available. Other Main sessions and forks do not inherit them or gain access to resume them. Reloading or resuming the same Main preserves ownership.

To use a profile in your current Pi instead of opening a Sub, start Pi with:

pi --profile reviewer

Starting Pi without --profile leaves your existing tools, model, and skills unchanged.

Customize a profile

Where profiles live

• Personal: ~/.pi/agent/subagent/profiles/<name>/
• Project: .pi/subagent/profiles/<name>/ in your project or an ancestor directory; loaded only when the project is trusted.

Each directory needs a config.json, with a name matching the directory name. A nearer project profile replaces a same-named ancestor or personal profile; settings are not merged. Legacy <name>.json profiles are also supported.

Instructions

Write the role in instructions.md beside config.json. It takes precedence over an inline "instructions": "..." field; if the file is absent, the inline field is used instead. Instructions add to Pi's normal project context, rather than replacing it.

Instruction files must be non-empty and no longer than 65,536 characters. An invalid or unreadable file is reported as an error, not silently ignored.

Run /reload after editing profiles. Already-open Subs keep their launch configuration; close and reopen them to use changes.

Optional settings

Add these fields to config.json as needed:

For a persistent specialist started with /sub:reviewer, invoking the command again from the same saved Main session resumes it after closure. A different Main session gets its own specialist. Manual-only profiles are not available for Pi to delegate on its own.

Sub extension allowlist

Add this to the profile's config.json, for example:

"extensions": ["npm:pi-model-calibration"]

Entries accept Pi's npm, git:, HTTP(S) repository URLs, builtin: identifiers, and local extension files or package directories. Relative local paths resolve from the configuration file's directory; absolute paths and ~/ work too. Missing local paths fail startup; repeated entries load once. Package specs are resolved by Pi in the Sub and may download or install packages, never while Main reads the profile.

npm: / git: entries use Pi's temporary package cache; a globally installed package may not be present there. For offline use, list the installed entry file directly, for example "extensions": ["~/.pi/agent/npm/node_modules/pi-model-calibration/index.ts"], to avoid another download.

Omitting the field or using [] loads no extra plugins. Subs still use --no-extensions: only communication/Herdr integration, normal MCP support, selected tools' extension dependencies, and this allowlist load explicitly. Other Main plugins are not inherited. Project profiles still require project trust; same-named overrides replace rather than merge allowlists.

This field controls Sub launches only; it does not dynamically load extensions in the current process started with pi --profile. Use Pi's -e or normal extension configuration for that case. Loading an extension does not automatically add its tools to the profile's tools; custom non-MCP tools must still be available in Main.

Extensions can execute code, read context, and change prompts. This is not a sandbox; list only trusted plugins. After editing, reload Main and close/reopen affected Subs. For model-calibration, its rules must also match the Sub's selected model before calibration text is injected.

Profile-specific skills

Put skills inside the profile directory to load them only when that profile is selected. No skills field is needed:

reviewer/
├── config.json
├── instructions.md
└── skills/
    └── code-review/
        └── SKILL.md

Delegation rules for your main Pi

Use ~/.pi/agent/subagent/MAIN.md or a trusted project's .pi/subagent/MAIN.md for rules such as:

Ask the reviewer profile to review code changes before declaring a task complete.

These instructions apply only to your main Pi, not to its Subs. Keep shared project rules in AGENTS.md.

Clean up deleted sessions

Persistent Subs use Pi's native session store alongside ordinary sessions, with IDs of the form sub-<UUID>:

~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_sub-<UUID>.jsonl

Same-cwd Subs inherit Main's session directory (including --session-dir overrides); Subs launched in another cwd use Pi's normal storage for that cwd. Ephemeral Subs still use --no-session. Native /resume can discover saved Subs; --continue may therefore select a Sub if it is the most recent session.

Ownership is stored in both directions: Main's subagent-run custom entries record Sub IDs and paths, and each Sub's subagent-owner custom entry records its own ID and Main's ID and file path. These entries do not enter model context. Reloading or resuming does not duplicate unchanged ownership metadata.

• /clean-sub permanently deletes orphaned Sub JSONL files across Pi's native session store and the current custom session directory, plus orphaned runtime communication directories. A Sub is orphaned when its recorded Main ID cannot be found. Recorded Main file paths also protect owners stored outside native discovery.
• On Pi exit (session_shutdown with reason quit), the same cleanup runs automatically, limited to Subs whose session-header cwd matches the current cwd. Switching sessions, forking, and reloading do not trigger cleanup. Main existence is still checked across projects to protect cross-cwd Subs.
• The current session/owning Main is always preserved, including unsaved sessions. Missing ownership metadata is preserved with a warning; unreadable files, invalid headers, or conflicting ownership abort cleanup before deletion. Shared session directories, ordinary sessions, profiles, and settings are never deleted. No separate index or legacy-storage migration is used.

Close orphaned Sub tabs before cleaning; cleanup deletes files, not running agents. Custom stores other than the current session directory are not scanned for Sub files; run /clean-sub from those stores when needed.

Things to know

Messages use custom inbox cards and Pi’s native run preparation, without extra user-role wake messages. See messaging behavior.

• Herdr is required for Subs. There is no headless fallback. Up to four Subs can be open at once, and Subs cannot delegate further.
• Subs cannot fork or clone. /fork and /clone are cancelled in Sub tabs; Main sessions are unaffected.
• Profiles are not a sandbox. Subs run as your OS user. A read-only role is not a filesystem permission boundary.
• MCP follows Pi's normal configuration. Profiles select non-MCP tools; they do not isolate or filter MCP servers. Custom non-MCP tools must come from extensions already loaded in Main.
• Subs have separate conversations. They receive their task, profile, and normal project context—not Main's chat history. Include the details they need in the task.
• Reloading Main does not close Subs. Close tabs you no longer need. Hard crashes may require manual cleanup.

Fresh and resumed Subs start from a private 0600 POSIX shell script in their existing runtime communication directory. The terminal receives only the fixed short command sh "$PI_SUBAGENT_LAUNCH"; the script path travels through the tab environment, and Pi's full arguments are read from the file. No shell probe or long terminal input is needed, avoiding the macOS canonical line-input limit even while the shell initializes. The plugin waits up to 60 seconds for the expected Pi in the same pane and terminal to become idle before naming it and submitting the task. Startup remains cancellable, and failures attempt to close the new tab. See Herdr issue #4950.

The script unlinks itself after the shell opens it; Main also removes it once Pi is ready or a launch fails, times out, or is cancelled—even if tab rollback fails. Each new launch reclaims leftover launch scripts at least five minutes old only when their creator process is confirmed gone. Live processes, uncertain liveness, symlinks, unrelated files, and communication directories are preserved. Failures to inspect or remove abandoned scripts are warned about and skipped without blocking new launches or the rest of the sweep. Normal channel cleanup is unchanged; script cleanup does not depend on the operating system purging temporary files.

If a profile is missing or fails to start, run /profiles first. Check its directory/name match, project trust, and any referenced tools, skills, or extensions. If Herdr is unavailable, confirm Pi is running inside a Herdr workspace.

To hide or show Pi Subagent Subs in Herdr's Agents panel, see the optional Herdr companion plugin.

Development

npm install
npm run check
pi -e ./src/index.ts

Maintainers: see the release guide for CI and automatic npm publishing.