pi-agent-flow

Pi Agent Flow 🌊

Flow-state transition for the Pi coding agent.
Isolate context, run specialist agents in parallel, and get structured results back!

Why This Exists

Long conversations can get messy—context bloats, tool calls get duplicated, and the real signal gets lost in the noise. Pi Agent Flow solves this by forking each task into a focused, isolated child process with only the context it actually needs.

The parent stays clean; the workers stay focused.

• No more duplicate work: Skip re-running the same read or grep commands.
• Keep it clean: Your main conversation thread stays free from endless transcripts.
• Laser focus: Each flow locks onto its intent without getting distracted by past messages.
• Run in parallel: Batch multiple tasks concurrently and get clean, structured results back.
• Instant quick actions: Use trace or dispatch parameters to execute reads, writes, edits, or bash commands in one round-trip step without extra model latency.

See it in Action

Quickstart

Install the extension via the Pi CLI:

pi install npm:pi-agent-flow

Then, jump right in and transition tasks in parallel:

pi
{ "flow": [
  { "type": "scout", "intent": "Map auth code", "aim": "Find JWT logic" },
  { "type": "audit", "intent": "Audit auth module", "aim": "Security audit" }
] }

Pro tip: You can also add { "packages": ["npm:pi-agent-flow"] } to your ~/.pi/agent/settings.json file.

Developing this extension locally

If pi loads npm:pi-agent-flow from ~/.pi/agent/npm, rebuilds do not apply until you sync:

git clone https://github.com/tuanhung303/pi-agent-flow.git
cd pi-agent-flow
npm run verify:pi

verify:pi runs trace/flow UI regression tests and copies dist/ + agents/ into the pi npm install. Use npm run check:dist in CI or before PRs to block legacy -----/max context placeholders in dist/.

Deep Dive

Want to learn more? Check out our docs:

• Core Flows: Understand specialist workers (scout, build, debug, etc.).
• Custom Flows: Build your own specialized flows.
• Tools: Unified batching, web search, and interactive prompts.
• Structured Output: Learn about the clean JSON results you get back.
• Configuration: CLI flags, env vars, and slash commands.

Made for faster, smarter coding.