pi-subagents
Claude Code-style sub-agents and workflow orchestration for pi: parallel execution, live widget, fleet view, custom agent types, mid-run steering, and claude-compatible dynamic workflows.
Evidence shows: The extension runs with the user's local privileges, SECURITY.md explicitly states sub-agents run with the same privileges as the user, no sandbox, and advises users to monitor or containerize. Tool restrictions (denylist, allowed_subagents) exist but are not enabled by default, and user confirmation mechanisms (e.g., double-confirm to stop an agent) are only partial. Data flow transparency: README details session persistence, event bus, RPC, but does not clarify where data flows (e.g., uploads). Sensitive data handling: No dedicated mechanism found, but SECURITY.md lists credential leakage as out of scope. Dependency security: Simple dependency list, peerDependencies with version ranges, CI compatibility tests, but no dependency vulnerability scanning evidence. External effects: Extension executes commands and writes files, but under user authorization, and SECURITY.md defines boundaries. Rollback: Session resume exists, but no explicit rollback mechanism. Source attribution: Code and docs attribute to tintinweb, but publisher unverified. Deductions: User confirmation incomplete, sensitive data handling lacks dedicated measures, rollback unclear.
Evidence shows: README and code comments consistent, tests cover key modules (e.g., abortable), CI runs lint, typecheck, test. Dependency availability: peerDependencies declare pi version range, CI has compatibility tests, but no actual runtime verification. Failure messages: Code comments and tests indicate error handling, but no user-visible failure message examples. Deductions: Static review cannot verify runtime behavior, specific failure messages not shown in docs.
Evidence shows: README details multiple use cases (parallel agents, workflows, scheduling) and provides configuration options. Capability boundaries: Docs clearly describe tool restrictions, nested subagent depth limits, scheduling restrictions. Trigger precision: @mention syntax has clear rules to avoid misfires. Environment fit: Supports pi 0.84.0+, third-party adapters reported but untested. Deductions: Third-party adapters unverified, environment fit based on documentation claims.
Evidence shows: README well-structured with sections for features, install, quick start, UI. Install notes clear, npm and dev mode provided. Naming stability: Tool names and config keys consistent across docs. Examples and FAQ: README provides multiple examples, but no FAQ section. Known limitations: SECURITY.md and README mention some limitations (e.g., headless mode doesn't wait for scheduled). License: MIT license file present. Versioning changelog: package.json has version, but no CHANGELOG file. Maintenance responsibility: Code and docs show active maintenance, but publisher unverified. Deductions: No FAQ section, no CHANGELOG file.
Evidence shows: Output usability: Agent results presented as notifications and expandable, supports Markdown. Marginal value: Provides Claude Code-style features, potentially valuable to pi users. Cost-benefit: Docs mention token counts and context window utilization, but no performance benchmarks. Deductions: Static review cannot assess actual effectiveness, cost-benefit lacks data support.
Evidence shows: README feature descriptions consistent with code comments and tests, but no external verification. Cross-source corroboration: No third-party independent verification. Fact-inference separation: Docs distinguish feature descriptions and design decisions (e.g., comments explaining rationale). Deductions: Lack of external verification, some claims (e.g., third-party adapters) unsubstantiated.
- Sub-agents run with the same privileges as the user, no sandbox, use in trusted environments or containerize.
- User confirmation mechanisms are incomplete; some operations (e.g., stopping an agent) require double confirmation, but other high-risk actions may lack confirmation.
- Sensitive data handling lacks dedicated measures; SECURITY.md lists credential leakage as out of scope, users must protect themselves.
- Dependency security lacks vulnerability scanning evidence; recommend regular dependency checks.
- Publisher identity unverified; assess trust cautiously.
What does this agent do, and when should you use it?
pi-subagents is a pi extension that brings Claude Code-inspired autonomous sub-agents and workflow orchestration to pi. It allows users to spawn specialized agents that run in isolated sessions, each with its own tools, system prompt, model, and thinking level. Agents run in the background by default, support parallel execution, and are monitored via a live widget and FleetView. The extension supports custom agent types, mid-run steering, session resume, graceful turn limits, and a deterministic scripted workflow tool called SubagentWorkflow. It requires pi 0.84.0 or newer and is installed as an npm package. The extension also includes features for persistent agent memory, git worktree isolation, skill preloading, and cross-extension RPC.
The extension provides an Agent tool to launch sub-agents with parameters such as prompt, subagent_type, and run_in_background. Agents run in isolated sessions with their own tools and models. Agent types are defined in Markdown files under .pi/agents/ with YAML frontmatter specifying tools, model, thinking, and tool restrictions. An interactive /agents menu manages running agents, agent types, scheduled jobs, and workflows. It renders a live widget and FleetView of running agents, supports @mentions to communicate with agents, and includes a SubagentWorkflow tool that runs deterministic JavaScript scripts orchestrating multiple agents using functions like agent(), parallel(), and pipeline(), executing in a node:vm sandbox. It supports schedules (cron, interval, one-shot), resume sessions from disk, and configurable concurrency limits. Completion notifications include result previews and structured XML.
- Developers who need to parallelize multiple tasks such as codebase exploration, planning, or refactoring, each with its own model and tools, in a controlled manner.
- Pi users wanting predefined specialized agents like Explore, Plan, auditor for code review, testing, or auditing, customizable or creatable via the /agents menu.
- Organizations needing deterministic, reproducible workflows that orchestrate multiple sub-agents, such as a two-phase security audit, run via saved scripts.
- Development teams wanting to schedule long-running background agents like weekly code reviews to fire automatically at set intervals (cron or interval syntax) and get notified on completion.
- Users who need to monitor and control multiple sub-agents during a long session, adjusting or stopping them via a FleetView, conversation viewer, and @mentions.
- Power users who want a high degree of observability into parallel executions, with a live workflow inspector, conversation views, and the ability to pause, skip, or retry individual agents.
What are this agent's strengths and limitations?
- Offers a more complete sub-agent abstraction and capability set than ad-hoc custom scripts, with a clean design borrowing from Claude Code's Agent tool and conventions.
- Includes a rich feature set including parallel execution, scheduling, workflow scripts, @mentions, custom agent types, and persistent memory, all unified in one package.
- Provides extensive live monitoring and interaction: a live widget, FleetView, conversation viewer, and mid-run steering and stopping, giving users high transparency and control.
- Agents can be launched with context inheritance or forced clones, custom agent types, and customization either per project or globally.
- This is a pi-specific extension; it will not work outside the pi ecosystem and requires a specific runtime and UI to operate.
- Requires pi 0.84.0 or newer, which may necessitate upgrading existing installations for compatibility.
- The feature set has a steep learning curve, with many tools, settings, and configurations that require documentation reading to master.
- While adapters for other agent frameworks exist, their compatibility is not fully tested nor maintained by this project and may break with pi releases.
How do you install or deploy this agent?
Ensure pi version 0.84.0 or newer. Install via pi install npm:@tintinweb/pi-subagents. For development, run with pi -e ./src/index.ts.
How do you use this agent?
After installation, sub-agents are launched via the Agent tool. For example: Agent({subagent_type: "Explore", prompt: "Find all files that handle authentication", description: "Find auth files", run_in_background: true}). Agents run in the background by default and notify you on completion. To run in the foreground and get the result inline, set run_in_background: false. Define custom agent types by creating Markdown files in .pi/agents/ or .agents/agents/ directories, corresponding to the configuration in the /agents menu. Use @type handle to interact with running agents. To run a workflow, call the SubagentWorkflow tool with a script, or invoke via /agents → Workflows, and use the CLI flag --subagents-workflow-file=<path>.
How does this agent compare with similar options?
The extension explicitly compares itself to Claude Code, stating it brings 'the same tool names, calling conventions, and UI patterns' and aims to be familiar to Claude Code users. Thus, a natural comparison is with Claude Code's Agent tool and Workflow tool.
FAQ
Do I need an Anthropic API key or Claude subscription to use this extension?
Can sub-agents access my filesystem and execute commands?
tools: frontmatter in custom agent types. Git worktree isolation is supported via isolation: worktree.What happens if an agent hits a timeout or is stopped?
How do I get the result of a background agent when it finishes?
get_subagent_result tool to retrieve the full text. Additionally, the conversation remains in the /agents menu for a short time.