pi-taskflow Guide: Build Resumable DAG Workflows in Pi CLI with 18 Agents

pi-taskflow Guide: Build Resumable DAG Workflows in Pi CLI with 18 Agents

pi-taskflow is a zero-dependency Pi extension that brings declarative, resumable, DAG-shaped multi-phase taskflows to the Pi coding agent. It ships 18 built-in agents across 6 model roles, supporting 8 phase types: agent, parallel, map (dynamic fan-out over arrays), gate (quality checks), reduce (aggregation), approval (human-in-the-loop pause), loop (iterate-until-done), tournament (best-of-N with judge), and flow (composition of saved sub-flows). The key innovation is cross-session resume: every completed phase is written to disk, so a failed run can be continued later with cached phases skipping automatically. (Source: github.com/heggria/pi-taskflow)

The Real Problem

Multi-step tasks in Pi require manual context management. Research, plan, implement, review, test — each step needs focused attention, but doing everything in one session bloats the context. Doing separate sessions means losing continuity. According to pi-taskflow's ecosystem analysis (June 2026), the Pi ecosystem has 20+ delegation extensions but pi-taskflow is the only one combining declarative DAGs, cross-session resume, and zero dependencies. Teams building multi-step Pi workflows report spending 40% of their time managing tool handoffs rather than doing actual work.

[ STAT ] 40% of time in multi-step Pi workflows is spent on tool handoffs, not actual work. — pi-taskflow ecosystem analysis, June 2026

What This Workflow Actually Does

pi-taskflow lets you define multi-agent pipelines as declarative JSON. The runtime executes phases in dependency order, fans out over arrays with the map phase, pauses for human approval when needed, and saves state so a crash doesn't lose progress.

[TOOL: pi-taskflow] Zero-dependency DAG engine. 18 built-in agents. 8 phase types. Install: pi install npm:pi-taskflow.

[TOOL: Map Phase] Dynamic fan-out over an array — one subagent per item. Items run in parallel with bounded concurrency.

[TOOL: Approval Phase] Human-in-the-loop pause. Presents output for approve/reject/edit before continuing.

Who This Is Built For

For Pi CLI developers building multi-phase automation: research, plan, implement, review, test in sequence with crash recovery. pi-taskflow's resume means no more restarting from scratch.

For teams using Pi for code review: save a 'review all focused changes' flow as a /tf:review-fixes command. One tap runs the full pipeline.

For engineers running long Pi background tasks: approval gates inject human review at critical decision points without pausing the entire pipeline.

How It Runs Step by Step

1. Flow Definition: Write a declarative JSON flow. Each phase specifies type, task, agent model, dependencies, and gates.

2. Execution: /tf:run flow-name runs the flow. The DAG is validated and phases execute in dependency order.

3. Map Fan-Out: For array-based tasks, one subagent spawns per item with bounded concurrency.

4. Approval Gate: The flow pauses at approval phases, presents output, and waits for human decision.

5. Cross-Session Resume: If the session crashes, /tf:resume runId loads saved state and skips cached phases.

6. Loop Iteration: The loop phase runs a body task until a condition is met or a cap is reached.

Setup and Tools

pi-taskflow v0.0.13: pi install npm:pi-taskflow. Zero third-party dependencies. Gotcha: DAG must be acyclic — cycles are rejected at validation.

Pi CLI v0.69+: npm install -g @badlogic/pi-coding-agent. Gotcha: subagent spawning requires child_process.spawn. Containerized Pi must have spawn available.

The Numbers

▸ Crash recovery: 100% manual re-run → 80-95% phase reuse with input-hash resume ▸ Multi-phase task time: 2-3 hours sequential → 20-45 minutes parallel DAG ▸ Flow definition time: 30-60 min bash scripts → 5-10 min JSON DSL ▸ Agents included: 0 bundled → 18 built-in agents across 6 model roles ▸ Time to first ROI: first saved flow becomes permanent /tf:command (Source: pi-taskflow docs, June 2026)

What It Cannot Do

1. No detached background execution — the Pi session must remain open.
2. Map phase requires JSON array input. Text lists need a conversion phase first.
3. No visual flow builder — all DAG design is code-first.

Start in 10 Minutes

1. (2 min) Install pi-taskflow: pi install npm:pi-taskflow
2. (5 min) Write your first flow: define a two-phase agent→parallel flow as a JSON file
3. (3 min) Run it: /tf:run your-flow-name and watch the progress output

Frequently Asked Questions

Q: How does pi-taskflow compare to pi-crew for multi-agent workflows? A: pi-taskflow is zero-dependency with declarative JSON DSL, cross-session resume, and 8 phase types. pi-crew is heavier — durable state, worktree isolation, Prometheus observability. Choose pi-taskflow for lightweight DAG pipelines, pi-crew for production-grade team orchestration. (Source: pi-taskflow PI-ECOSYSTEM.md, June 2026)

Q: Can I save a flow as a Pi slash command? A: Yes. Saved flows in ~/.pi/flows/ become /tf:command shortcuts. Run /tf:list to see all saved flows.

Q: What happens if a phase fails? A: The runtime reports the failure with the phase's output and error. You can configure retry with backoff on individual phases. The run can be resumed from the failed phase after fixing the issue.

Q: Does pi-taskflow work with any Pi model? A: Yes. pi-taskflow uses whichever model your Pi session is configured with. The 18 built-in agents have recommended model roles but fall back to the session default.