pi-subagents

A pi extension that allows the main agent to spawn parallel sub-agents, with each sub-agent's latest output rendered in a rolling TUI window inline with the main agent's conversation history.

Sub-agents can optionally use named profiles that pre-configure provider/model, system prompts, thinking levels, and other model settings. Profiles are stored as individual .md files with YAML frontmatter.

Installation

Installed as a pi package (Recommended)

pi install git:github.com/harms-haus/pi-subagents

Or use https:// / ssh:// instead of git: if you prefer.

Local Development

Clone the repo and install the local path (use -l for project-local install):

cd pi-subagents
pi install . -l

Usage

Once installed, the LLM can use the tool:

{
  "delegate_to_subagents": {
    "tasks": [
      {
        "name": "linter-src",
        "prompt": "Review and fix all linting errors in the src/ directory."
      },
      {
        "name": "linter-tests",
        "prompt": "Review and fix all linting errors in the tests/ directory.",
        "profile": "fast-worker"
      }
    ]
  }
}

Providing File Context

Each task can include a files array to read file contents and prepend them to the sub-agent's prompt:

{
  "delegate_to_subagents": {
    "tasks": [
      {
        "name": "fix-lint",
        "prompt": "Fix all linting errors in this file.",
        "files": ["src/utils.ts"]
      }
    ]
  }
}

File specs support line ranges: { "path": "src/main.ts", "start": 10, "end": 50 }, { "path": "log.txt", "tail": 20 }, or { "path": "config.json", "head": 5 }.

See docs/tools-reference.md for complete parameter documentation.

After delegate_to_subagents completes, it returns session IDs for each task. Use get_subagent_output to retrieve the final text output:

Parameters

| Name | Type | Required | Description | | --------- | ------------------------------------------------------------------ | -------- | ---------------------------------------------------------------- | | tasks | Array<{name, prompt, cwd?, profile?, timeout?, resume?, files?}> | Yes | Array of tasks to delegate. Each gets its own sub-agent process. | | profile | string | No | Default profile for all tasks (overridden by per-task profile) |

Each task:

| Field | Type | Required | Description | | --------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Yes | Display label shown in the TUI window header | | prompt | string | Yes | Prompt sent to the sub-agent (same as typing into pi directly) | | cwd | string | No | Working directory for the sub-agent (default: current directory) | | profile | string | No | Named profile to use for this sub-agent (see below) | | timeout | number | No | Timeout in seconds for this sub-agent. Default: 600. Timeouts auto-extend when the sub-agent is actively producing output — after the initial timeout expires, the sub-agent is only killed after a configurable idle period (see extend_timeout_debounce setting). | | resume | string | No | Previous session ID to resume from. The resumed sub-agent receives the prior session's transcript as context. Only completed or errored sessions can be resumed. | | files | Array<FileSpec> | No | File paths to read and prepend to the sub-agent's prompt. See "Providing File Context" above. |

The maxLinesPerWindow setting is configured in settings.json under subagents.maxLinesPerWindow (default: 15).

Retrieving Sub-agent Output

After delegate_to_subagents completes, each task has a session ID. Use these tools to retrieve results:

• get_subagent_output(sessionId) — Returns the last assistant text output from a sub-agent session. For resumed sessions, returns the latest run's output. This is the primary way to get results.
• get_subagent_session(sessionId) — Returns the full session transcript including all messages, tool calls, and results. For resumed sessions, returns all runs' data concatenated. Use for debugging.
• list_subagent_profiles() — Lists all available subagent profiles that can be used with delegate_to_subagents.

{
  "get_subagent_output": {
    "sessionId": "a1b2c3d4e5f6a7b8"
  }
}

Resuming Sessions

Use the resume parameter to continue work from a previously completed (or errored) sub-agent session. The resumed agent receives the full transcript of all prior runs prepended to its prompt:

{
  "delegate_to_subagents": {
    "tasks": [
      {
        "name": "continue-refactor",
        "prompt": "Continue the refactoring. Focus on the remaining utility modules.",
        "resume": "a1b2c3d4e5f6a7b8"
      }
    ]
  }
}

Key behaviors:

• The resumed agent's prompt is prefixed with Previously:\n\n<transcript>\n\nInstructions:\n\n<your prompt>, giving it full context of prior work.
• Only completed or errored sessions can be resumed. Running sessions will throw an error.
• A session can be resumed multiple times — each resume creates a new "run" appended to the session record.
• get_subagent_output returns output from the latest run only.
• get_subagent_session returns all runs concatenated with run separators.

Subagent Profiles

Profiles let you pre-configure the provider, model, system prompt, thinking level, and other settings for sub-agents. Each profile is a .md file with YAML frontmatter.

Profile Locations

| Scope | Directory | | ------- | --------------------------------- | | Global | ~/.pi/agent/agent-profiles/*.md | | Project | .pi/agent-profiles/*.md |

Project-local profiles override global profiles with the same name.

Example Profiles

~/.pi/agent/agent-profiles/code-reviewer.md:

---
name: code-reviewer
provider: anthropic
model: claude-sonnet-4-5
thinkingLevel: high
tools: read,bash,grep,find
---

You are an expert code reviewer. Focus on bugs, security issues, and performance problems. Be thorough but concise.

~/.pi/agent/agent-profiles/fast-worker.md:

---
name: fast-worker
model: dashscope/qwen3.5-plus
appendSystemPrompt: Be concise. Skip explanations unless asked.
thinkingLevel: off
---

.pi/agent-profiles/researcher.md (project-local):

---
name: researcher
provider: openai
model: gpt-4o
appendSystemPrompt: Use web search to find information. Cite sources when possible.
---

You are a research assistant.

Profile Fields

| Field | Type | Description | | -------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | name | string | Required. Profile identifier (from YAML frontmatter name field) | | provider | string | Provider name (e.g., "anthropic", "openai", "dashscope") | | model | string | Model pattern or ID. Supports "provider/id" format and ":thinking" shorthand (e.g., "sonnet:high") | | systemPrompt | N/A | Set via the body of the markdown file (text after ---). Replaces the default system prompt entirely. | | appendSystemPrompt | string | Append text to the default system prompt | | thinkingLevel | string | Thinking level: "off", "minimal", "low", "medium", "high", "xhigh" | | noTools | boolean | Disable all tools | | tools | string or string[] | Comma-separated string or YAML array of tool names to enable (allowlist) | | excludeTools | string or string[] | Comma-separated string or YAML array of tool names to exclude (blacklist; mutually exclusive with tools) | | noExtensions | boolean | Disable all extensions | | extensions | string or string[] | Comma-separated string or YAML array of extension paths to load | | noSkills | boolean | Disable skills. Mutually exclusive with suggestedSkills and loadSkills | | suggestedSkills | string or string[] | Skill names to suggest to the sub-agent via --skill CLI flags; the model chooses whether to load them | | loadSkills | string or string[] | Skill names to pre-load into the sub-agent's system prompt (content wrapped in <loaded_skill> XML tags) | | noContextFiles | boolean | Disable AGENTS.md/CLAUDE.md context files | | apiKey | string | Custom API key (stored as PI_API_KEY env var, not in CLI args) | | extraArgs | string or string[] | Comma-separated string or YAML array of additional CLI arguments |

Array fields (tools, extensions, extraArgs, suggestedSkills, loadSkills) support both YAML arrays and comma-separated strings:

tools:
  - read
  - bash
  - grep

or equivalently:

tools: read,bash,grep

Using Profiles

Per-task profile — each task specifies its own profile:

{
  "delegate_to_subagents": {
    "tasks": [
      { "name": "review", "prompt": "Review src/...", "profile": "code-reviewer" },
      { "name": "research", "prompt": "Find best practices for...", "profile": "researcher" }
    ]
  }
}

Default profile for all tasks — set at the top level, overridden by per-task profiles:

{
  "delegate_to_subagents": {
    "profile": "fast-worker",
    "tasks": [
      { "name": "task-a", "prompt": "..." },
      { "name": "task-b", "prompt": "...", "profile": "code-reviewer" }
    ]
  }
}

Profile Resolution Order

1. Per-task profile field (highest priority)
2. Top-level profile parameter
3. If neither is specified, no profile is applied (uses pi defaults)

Profiles are loaded from .md files:

1. Global: ~/.pi/agent/agent-profiles/*.md
2. Project-local: .pi/agent-profiles/*.md (overrides global profiles with the same name)

The profile cache refreshes every 5 seconds.

Settings

Additional settings are configured in settings.json under the subagents key:

| Setting | Type | Default | Description | | ------------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | maxLinesPerWindow | number | 15 | Number of lines shown in each sub-agent's rolling TUI window | | commandPreviewWidth | number | Terminal width − 4 (TTY) or 160 (non-TTY) | Controls tool call preview truncation width in the rolling window. In TTY mode, terminal width − 4 is used as a hard override — settings files are never consulted. In non-TTY mode, falls back through settings files (global → project → default 160). Minimum: 20 | | extend_timeout_debounce | number | 30 | Seconds of idle time (no output activity) before a timed-out sub-agent is killed. The initial timeout starts this idle window; any output resets it. Range: 0–300. | | looping_tool_count | number | 5 | Number of consecutive tool calls checked for loop detection. Set to 0 to disable. Range: 0–50. | | looping_tool_similarity | number | 0.95 | Bigram similarity threshold for loop detection. When the last looping_tool_count tool calls are all pairwise similar above this threshold, the sub-agent is killed. Range: 0–1. |

Settings are loaded from ~/.pi/agent/settings.json (global) and .pi/settings.json (project-local, overrides global). Note: commandPreviewWidth settings are only consulted in non-TTY mode.

The /profile Command

Use /profile interactively to manage subagent profiles without editing files by hand:

| Command | Description | | ------------------------ | -------------------------------------- | | /profile list | List all profiles with summaries | | /profile show <name> | Display full details of a profile | | /profile <name> | Alias for show | | /profile create <name> | Interactively create a new profile | | /profile edit <name> | Interactively edit an existing profile | | /profile delete <name> | Delete a profile |

Interactive Editor

/profile create and /profile edit walk you through each setting:

1. Scope — save to global (~/.pi/agent/agent-profiles/) or project-local (.pi/agent-profiles/) directory
2. Provider — e.g. anthropic, openai, dashscope
3. Model — supports provider/id and :thinking shorthand
4. System prompt — the body text of the .md file (replaces default system prompt)
5. Append system prompt — optionally append to the default
6. Thinking level — off, minimal, low, medium, high, xhigh
7. Tools — choose to disable all (noTools), enable a specific set (tools), or exclude specific tools (excludeTools)
8. Extensions — restrict or disable
9. Skills — if skills are already set, offers to remove them; otherwise asks whether to configure skills, then prompts for comma-separated suggested and/or pre-loaded skill names
10. Review & save — shows full profile as markdown before confirming

You can skip any field by answering "No" — it will be omitted from the profile (using pi defaults).

Features

• Parallel execution: Multiple sub-agents run concurrently (up to 4 at a time by default)
• Rolling window: Each sub-agent shows its latest N lines in real-time
• Live updates: The TUI re-renders as sub-agents stream output
• Expandable (Ctrl+O): Collapse to rolling window, expand to see full sub-agent output
• Error handling: Non-zero exit codes and errors are highlighted
• Abort support: Hitting Escape cancels all running sub-agents
• Session resume: Continue work from completed/errored sessions with full transcript context
• Per-task timeouts: Configurable timeout per sub-agent (default 600s), with auto-extension while the agent remains active
• Loop detection: Automatically kills sub-agents that repeat the same tool calls in a tight loop
• Session persistence: Sessions are persisted to the main agent's session log immediately after each sub-agent completes. On agent restart, sessions are reconstructed from the log — no data is lost across restarts.

Architecture

Main Agent TUI
  │
  └── delegate_to_subagents
        │
        ├── Resolve profiles from .md files
        │   ├── Global: ~/.pi/agent/agent-profiles/*.md
        │   └── Project: .pi/agent-profiles/*.md
        │
        ├── Validate profile skills (suggestedSkills/loadSkills vs noSkills)
        │
        ├── Resolve skill names → file paths (suggestedSkills) or injected content (loadSkills)
        │
        ├── Validate resume targets (must be completed/errored)
        │
        ├── For each task (concurrency ≤ 4):
        │   │
        │   ├── [resume?] Inject prior session transcript into prompt
        │   │
        │   ├── Spawn: pi --mode json -p --no-session [profile args...] "prompt"
        │   │   │
        │   │   ├── Parse JSONL stdout events
        │   │   ├── Update rolling window (latest N lines)
        │   │   ├── Track tool calls & results
        │   │   └── [timeout?] Abort if task timeout exceeded
        │   │
        │   ├── Store session data (messages, status, exit code)
        │   └── persistSession → pi.appendEntry() (fault-tolerant)
        │
        ├── On session_start (restart/resume):
        │   └── Reconstruct sessionStore from persisted entries
        │       └── Stale "running" sessions → auto-converted to "error"
        │
        └── Return session IDs → get_subagent_output / get_subagent_session

Each sub-agent is a separate pi process in JSON mode. We parse JSONL events from stdout and maintain a rolling line buffer per agent. The tool's renderResult builds a Container of Text components, displayed inline with the conversation history.