pi-agent-flow Guide: 6 Specialist Agent Flows for Clean Cognitive Switching in Pi CLI

pi-agent-flow Guide: 6 Specialist Agent Flows for Clean Cognitive Switching in Pi CLI

pi-agent-flow is a flow-state delegation extension for the Pi coding agent that runs specialist agents in isolated forked contexts. It ships 6 bundled flows — scout (file discovery), debug (error investigation), build (implementation), craft (architecture planning), audit (security/quality review), and ideas (creative brainstorming) — each with its own tool set, model tier, and context inheritance policy. The core idea is simple: instead of one agent doing everything in a bloviated session, fork each cognitive mode into its own clean context. (Source: github.com/tuanhung303/pi-agent-flow)

The Real Problem

Long Pi conversations bloat context, duplicate tool calls, and bury signal in noise. A developer debugging an issue might grep the same code 3 times because earlier results scrolled off the context window. According to pi-agent-flow documentation, duplicate tool calls account for 40% of token spend in long sessions. The standard one-conversation pattern also makes cognitive switching painful — going from debugging stack traces to planning architecture requires the model to completely shift approach, which it does poorly when the context is full of logs.

[ STAT ] 40% of token spend in long Pi sessions comes from duplicate tool calls. — pi-agent-flow documentation, June 2026

What This Workflow Actually Does

pi-agent-flow forks each specialist task into an isolated Pi child process with a sanitized session snapshot. The parent session stays clean while workers handle focused tasks and return structured results.

[TOOL: scout] File discovery flow. Uses batch, bash, find, grep, ls, web. Lite model tier. Returns structured file maps.

[TOOL: build] Implementation flow. Uses batch, bash, find, grep, ls, web. Flash model tier. Returns code diffs.

[TOOL: audit] Review flow. Uses batch, bash, find, grep, ls, web. Flash model tier. Returns structured findings.

Who This Is Built For

For Pi CLI developers debugging production issues: the debug flow provides a clean slate with only error context — no distraction from earlier conversation topics.

For architects planning features: the craft flow inherits context but biases toward broad architectural thinking rather than implementation details.

For developers who frequently switch modes: going from implement to debug to review is instant with flow selection — no more struggling with context pollution.

How It Runs Step by Step

1. Mode Selection: Invoke a flow by name: [scout], [debug], [build], [craft], [audit], or [ideas].

2. Context Forking: The flow receives a sanitized session snapshot. Reasoning artifacts and steering hints are stripped.

3. Isolated Execution: The child process runs with tools specific to its mode. Structured JSON returns: summary, files, actions, nextSteps, reasoning.

4. Post-Flow Advisory: The system suggests the next flow. Code → review. Debug → code. Ideas → craft.

Setup and Tools

pi-agent-flow: pi install npm:pi-agent-flow. 6 bundled flows, tiered model strategies. Gotcha: clean-slate mode strips ALL session history. Use only for unbiased creative work.

Built-in web search: Brave and DuckDuckGo via HTML endpoints. No API keys required. Gotcha: best-effort service may be rate-limited.

The Numbers

▸ Duplicate tool calls: 40% token spend → under 5% with flow isolation ▸ Context-related failures: 35% single-session → under 8% with flow forking ▸ Mode switching time: 5-10 min re-orientation → instant flow selection ▸ Creative quality: baseline with biased context → 2-3x novelty with clean-slate ideas ▸ Time to first ROI: first [scout] flow saves 15+ minutes of manual exploration (Source: pi-agent-flow docs, June 2026)

What It Cannot Do

1. Flow child processes have bounded context. Critical parent context must be passed in the task prompt.
2. Post-flow advisories are suggestions. No automatic flow chaining in the base extension.
3. Completed flows return text summaries, not interactive sessions. No follow-up questions.

Start in 10 Minutes

1. (2 min) Install pi-agent-flow: pi install npm:pi-agent-flow
2. (5 min) Run a scout flow: [scout] map the architecture of your project
3. (3 min) Run a build flow: [build] implement a small feature in your project

Frequently Asked Questions

Q: What model tiers does pi-agent-flow support? A: Lite (fast/cheap for scout/debug), Flash (balanced for build/audit), Full (best quality for craft/ideas). Configured via flowModelConfigs in settings.json.

Q: Can I create custom flows? A: Yes. Custom flows are defined as Markdown files with YAML frontmatter in ~/.pi/agent/agents/ or .pi/agents/.

Q: How do post-flow advisories work? A: When certain flows complete, the system injects a suggestion for the next logical flow. Code → review. Debug → code. The advisory is a hint, not an automatic trigger.