subagents

Delegate tasks to parallel headless pi subagents running in tmux with fresh context.

5|2|Updated Mar 9, 2026
One-click install
npx skills add https://github.com/lauhon/pi --skill subagents-lauhon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: subagents
Source: https://github.com/lauhon/pi/tree/main/skills/subagents
Command: npx skills add https://github.com/lauhon/pi --skill subagents-lauhon

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running or context-heavy tasks consume the main AI session's context window and budget. This Skill offloads work to detached headless pi subagents running in tmux, each with fresh context and a cheap model, so the parent session stays lean while parallel work proceeds. ## Core Features & Use Cases - Parallel fanout: Spawn multiple children at once (e.g., separate correctness and test reviewers), then wait and collect each output file. - Role-based model selection: Pick the cheapest model per role, from lightweight recon to implementation, review, research, and ops work. - Lifecycle management: List, wait, peek, resume, kill, and clean child runs, with session scoping so each pi session only sees its own children. - Use Case: While refactoring a codebase, spawn a read-only reviewer child to audit the auth flow and a research child to investigate a library, continue your own edits, then read both outputs when the monitor reports completion. ## Quick Start Ask the agent to spawn a subagent that maps the authentication flow in this repository and report back the key files with a short summary.

Frequently Asked Questions about subagents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run parallel AI subagents for code review?

Spawn one child per review concern using sub spawn with a self-contained prompt file, then call sub wait with all names and read each result via sub out. Pass --tools read,grep,find,ls to keep reviewers read-only.

How do I delegate a task to a headless AI agent in tmux?

Use sub spawn with a name, working directory, and a self-contained task prompt describing the goal, file paths, and expected output. The child runs detached in tmux with fresh context and writes its result to an out file.

Which model should I use for different subagent tasks?

Use the cheapest model that fits the role: a lightweight model for recon and summaries, a stronger one for implementation, a high-quality model for review and planning, and a web-capable model for research or ops work. Pass the choice via --model.

Can subagents access the web or use extensions?

Extensions are off by default in headless children. Research children need web tools enabled explicitly by passing --ext with the path to the web access extension when spawning.

When should I resume a subagent instead of spawning a new one?

Resume only for tightly related corrections where the child's prior file map and decisions materially help. Prefer a fresh spawn with a checkpoint prompt when crossing topic boundaries or after three to four corrective turns.

Why should I avoid running two writer subagents at once?

Two children editing the same worktree concurrently can conflict and corrupt each other's changes. Parallelize read-only work like reviews and recon, but keep only one writer child active at a time.