@tintinweb/pi-subagents

A pi extension that brings Claude Code-style autonomous sub-agents and workflow orchestration to pi. Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level. Run them in the background (the default) or block on them, steer them mid-run, resume completed sessions, and define your own custom agent types. When the orchestration shouldn't be improvised, hand a deterministic JavaScript script to the SubagentWorkflow tool — agent(), parallel(), pipeline() — and scripts written for Claude Code's Workflow tool run here unchanged.

https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543

Features

• Claude Code look & feel — same tool names, calling conventions, and UI patterns (Agent, get_subagent_result, steer_subagent) — feels native
• Parallel background agents — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 10) and smart group join (consolidated notifications)
• Live widget UI — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons. Configurable via /agents → Settings → Widget: all (every agent), background (default — hides foreground runs, which already render inline as the Agent tool result), or off
• FleetView — Claude Code-style navigable list of main + every running subagent rendered below the editor (earliest-launched first). Press ↓ (or ←) at an empty prompt to jump in, ↑/↓ to move the selection, Enter to open the selected agent's live, auto-updating conversation, Esc to return. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via /agents → Settings → Fleet view
• Conversation viewer — select any agent in /agents to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). Steer a running agent inline by pressing Enter to open a composer, typing, then Enter to send (Esc or an empty submit returns) — the message appears as a user message and redirects the agent after its current tool. Stop a still-running agent by pressing x (then x again to confirm) — both work for background agents too. Assistant text renders as Markdown; m cycles that between off, assistant-only and everything (see Viewer markdown)
• Custom agent types — define agents in .pi/agents/<name>.md or .agents/agents/<name>.md (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions, and Claude Code-compatible colored name badges
• Nested subagents — opt-in, default-off delegation: a custom agent that sets allowed_subagents gets its own ownership-scoped Agent, get_subagent_result, and steer_subagent tools, depth-capped from the main session (default 2). It can control only its own children, they are stopped when it finishes, and their transcripts and token spend roll up to it. The allowlist is a privilege boundary — a child runs with its own tools, so pick it as carefully as tools: itself
• Agent mentions — subagents are first-class: type @explore also check the RPC path at the prompt and it goes to that agent instead of the main model, without a word of it entering the chat. One syntax covers the whole lifecycle — message it while it runs, resume it once it has finished, reopen its session from disk long after that, or start it if it never ran. Mentioning an agent that isn't running spawns it through an off-screen clone of the conversation, so it gets Claude Code's context-written prompt and a real Agent tool call without a word of it reaching the chat; direct mode starts it here from your text instead, with no model call at all. The orchestrator can name an agent so you address it as @auth-audit, and handles work in steer_subagent/get_subagent_result too. @ completes live agents, resumable ones, and startable types alongside pi's file completion; @main forces text back to the main model. Toggle via /agents → Settings → Agent mentions
• Scripted workflows — a SubagentWorkflow tool that runs a deterministic JavaScript script orchestrating many subagents: agent(), parallel(), pipeline(), phase(), log() and args, with a pure-literal meta block declaring the phases. pipeline() has no barrier between stages, so one item can be in a later stage while another is still in the first — unlike parallel(), which idles every fast agent until the slowest finishes. Runs in the background with a live card, inspectable via /agents → Workflows or by selecting the run in FleetView. agent() also takes gate: "npm test" to verify a child by running a command (inside its worktree, when isolated) rather than asking another model, and resume: "<label>" to continue a child instead of re-paying its context. Scripts run in a node:vm sandbox on a worker thread where Date.now(), Math.random() and eval throw. On by default, but it stands down for company: if another extension already provides a Workflow or SubagentWorkflow tool, this one warns and disables itself for the session rather than offering the model two orchestrators. Pin it either way with "workflowsEnabled" in subagents.json or /agents → Settings → Workflows. A script written for Claude Code's Workflow tool runs here unchanged: same globals, schema returns a validated object exactly as it does there, budget is present and always reports no token target (pi has no such directive) so its budget.total-guarded patterns still take the branch they were written for, and nested workflow() composes saved workflows one level deep. Full guide
• Mid-run steering — inj