pi-ultra-subagents

A focused Pi package for ultra-capable sub-agents.

It adds a subagent tool plus interactive $agent sessions so Pi can delegate work to isolated child Pi runtimes, optionally inherit the current session context, and merge structured results back into the parent conversation.

Features

• Isolated sub-agent execution in temporary child Pi processes.
• fresh and fork-current context modes.
• Single, parallel, and chained delegation through the subagent tool.
• Interactive $agent chat sessions in the TUI.
• $agent autocomplete for available sub-agents.
• /agents browser for inspecting available agent definitions.
• Structured completion through subagent_finish.
• Result merge modes: result-only, full-transcript, and none.
• Project-local agent confirmation before running repo-controlled agents.
• Bundled agents: researcher, reviewer, planner, scout, and worker.

Install

From npm after publication:

pi install npm:pi-ultra-subagents

From GitHub:

pi install git:github.com/liangxiao777/pi-ultra-subagents

For local development:

pi -e /path/to/pi-ultra-subagents

Or install a local checkout:

pi install /path/to/pi-ultra-subagents

After changing the package during a running Pi session, use /reload or restart Pi.

Usage

Interactive $agent chat

Start an embedded sub-agent chat from the main editor:

$researcher compare this implementation with upstream Pi package docs
$reviewer review the current diff for correctness and release blockers
$planner create a migration plan for extracting the package

Interactive behavior:

• Type $ and use completion to select an available agent.
• If no task is provided, Pi prompts for one.
• If the selected agent is project-local, Pi asks for confirmation first.
• Pi asks whether to inherit the current conversation context:
  • Yes: fork-current / inherited context.
  • No: fresh / isolated context.
• The embedded chat shows live child-agent activity and the active context mode.
• When leaving the embedded chat, choose how to save it back to the parent session:
  • Save final answer only
  • Save full transcript
  • Back to sub-agent session
  • Do not save

Tool-based delegation

Ask Pi to use the subagent tool for delegated work.

Single sub-agent:

Use the planner sub-agent to create an implementation plan for adding tests.

Fork current context into a child runtime:

Use subagent with agent "reviewer", task "review the current changes", and contextMode "fork-current".

Parallel delegation:

Run scout and reviewer in parallel: scout should map the codebase, reviewer should inspect the latest diff.

Chained workflow:

Use a chain: scout relevant files, planner designs the change from {previous}, worker implements from {previous}.

The tool accepts exactly one execution mode:

// Single
{ agent: "planner", task: "Create a plan" }

// Parallel
{
  tasks: [
    { agent: "scout", task: "Find relevant files" },
    { agent: "reviewer", task: "Review the current diff" }
  ]
}

// Chain
{
  chain: [
    { agent: "scout", task: "Find relevant files" },
    { agent: "planner", task: "Plan using this context: {previous}" }
  ]
}

Optional tool parameters:

| Parameter | Values | Default | Description | |---|---|---|---| | agentScope | user, project, both | user | Which agent sources to use. user includes package agents plus ~/.pi/agent/agents; project uses project agents only; both uses all. | | confirmProjectAgents | boolean | true | Prompt before running project-local agents. | | contextMode | fresh, fork-current | fresh | fresh starts an isolated child session. fork-current copies the current session prefix into the child runtime. | | mergeMode | result-only, full-transcript, none | result-only | Controls what is returned to the parent model. | | requireStructuredResult | boolean | false | Treat missing subagent_finish as an error instead of accepting an unstructured fallback. | | cwd | string | current cwd | Working directory for single mode. Each tasks[] or chain[] item can also set cwd. |

Context modes

• fresh: create a temporary empty child session.
• fork-current: copy the current session's stable prefix byte-for-byte, then append child-only sub-agent runtime instructions and the delegated task.

If the current parent session is ephemeral or cannot be copied, fork-current falls back to fresh. The TUI displays the actual mode used: fork-current / inherited or fresh / isolated.

Result merging

Sub-agents are instructed to finish by calling subagent_finish, which captures:

• status
• summary
• findings
• files
• changes
• nextActions
• openQuestions

mergeMode controls what the parent receives:

• result-only: compact structured result rendered from subagent_finish.
• full-transcript: full child output.
• none: only report that the sub-agent completed.

Browse agents

Use /agents to list available sub-agent definitions and preview their raw markdown files.

/agents          # same as /agents both
/agents both     # package + user + nearest project agents
/agents user     # package + user agents
/agents project  # nearest project agents only

Agent discovery locations:

• package agents: <installed-package>/agents/*.md
• user agents: ~/.pi/agent/agents/*.md
• project agents: nearest .pi/agents/*.md found by walking up from the current working directory

In both mode, same-name agents are resolved as project > user > package.

The main agent's system prompt is also augmented with a compact list of available sub-agents so it can choose the subagent tool when delegation is useful.

Agent definitions

Bundled agents live in agents/*.md and use YAML frontmatter:

---
name: planner
description: Creates implementation plans from context and requirements
tools: read, grep, find, ls, bash
model: claude-sonnet-4-5
---

System prompt for the agent goes here.

Fields:

• name: command/tool-facing agent name.
• description: shown in /agents, autocomplete, and system-prompt agent lists.
• tools: optional comma-separated tool allowlist for the child runtime.
• model: optional model override for the child runtime.

The extension discovers agents from:

• package agents bundled in this package
• user agents in ~/.pi/agent/agents
• project agents in .pi/agents when explicitly enabled with agentScope: "project" or "both"

Project agents are repo-controlled prompts. Keep the default confirmation enabled unless you trust the repository.

Runtime notes

• Child agents run through temporary Pi child processes in RPC mode.
• Child sessions are cleaned up after the sub-agent run finishes.
• Child UI requests such as select, confirm, input, editor, notify, status, and widgets are bridged back to the parent Pi UI where possible.
• The researcher bundled agent expects a local codex CLI when it performs Codex-backed research.

Package resources

This package exposes Pi resources through package.json:

{
  "pi": {
    "extensions": ["./extensions/subagent"]
  }
}

The agents/ directory is a custom resource consumed by extensions/subagent/agents.ts. It is kept inside the installed package and is not copied into ~/.pi/agent/agents.

Development

npm run pack:dry-run
npm run publish:dry-run

Before publishing:

1. Confirm npm pack --dry-run contains only intended files.
2. Ensure README install URLs match the final GitHub repository.
3. Run a local smoke test with pi -e ..
4. Publish with npm publish --access public.

Security

Pi packages run with your local permissions. This package spawns child Pi processes and can enable tools such as bash, read, edit, and write through configured agents. Review bundled and project-local agents before use.

License

MIT