Pi Dynamic Workflows
Turn complex Pi requests into routed, resumable, cross-checked fleets of parallel subagents.
- Source repo
- QuintinShaw/pi-dynamic-workflows
- Stars
- ★ 590
- Last updated
- 9d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 88/100 · Good
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An engineering team maintaining a large application can divide directories such as src/routes/ among subagents, inspect every file for missing authorization checks, and cross-validate the findings.
- Not a fit if
- Teams outside the Pi ecosystem needing standalone deployment or direct OpenAI/Claude API use
- Cost-sensitive users who can't absorb wide fan-out model spend
- Source review
- 88/100 · Good
What does this agent do, and when should you use it?
Pi Dynamic Workflows is a TypeScript package and Pi extension that converts one request into a JavaScript orchestration script executed across isolated subagents. Workflows use agent(), parallel(), pipeline(), and phase(), with routing by small, medium, or big tiers or by an exact provider and model. The package adds journaled and edited-script resume, Git worktree isolation, measured token and cost reporting, background execution, and an interactive /workflows navigator. Built-in patterns cover deep research, adversarial review, multi-perspective analysis, code review, and codebase audits, with results verified and synthesized into one response. It runs inside the Pi ecosystem and stores state under ~/.pi/workflows by default; the deterministic orchestration VM cannot access the filesystem or network directly, while spawned subagents use their assigned tools.
After a natural-language trigger or /workflows run <prompt>, Pi writes a deterministic JavaScript workflow. phase() labels stages, agent() starts fresh Pi subagent sessions, parallel() executes thunks concurrently, and pipeline() sends items through sequential stages; one run can fan out to 1,000 total agents with concurrency capped at 16. Each agent() call can select a tier, exact model, thinking level, agentType, JSON Schema, timeout, retries, and isolation: "worktree". Runtime helpers such as verify(), judgePanel(), loopUntilDry(), completenessCheck(), retry(), gate(), and checkpoint() provide review, repeated discovery, failure handling, or human approval. Successful calls are journaled, and resume replays cached results by positional call index while rerunning changed or subsequent calls. The background panel and /workflows navigator expose phases, models, agent state, tokens, cost, and throughput before the synthesized result is delivered to the conversation.
- An engineering team maintaining a large application can divide directories such as src/routes/ among subagents, inspect every file for missing authorization checks, and cross-validate the findings.
- A developer preparing a risky merge can run /code-review against the current diff, a Git range, one file, or a GitHub pull-request number and receive seven parallel review angles plus verification.
- A team undertaking a broad refactor can place editing agents in separate Git worktrees and branches to reduce conflicts between concurrent changes.
- A technical researcher can use /deep-research to distribute source gathering and cross-checking across subagents before receiving one cited synthesis.
- A Pi user with recurring audits can save a successful run as a reusable command and invoke it from another workflow through workflow(name, args).
- A cost-conscious team can route simple and difficult tasks to different model tiers, assign thinking levels and budgets, and inspect measured usage for each child session.
How do you install or deploy this agent?
Use Pi 0.80.8 or newer and ensure npm packages can be downloaded. Run:
pi install npm:@quintinshaw/pi-dynamic-workflowsThen reload Pi:
/reloadThe extension can rank authenticated models automatically. To define explicit small, medium, and big mappings, run /workflows-models and assign provider/modelId values. Authenticate the relevant model providers in Pi before running workflows that call them.
How do you use this agent?
After installation and reload, submit a decomposable request containing the bounded word workflow or workflows, for example:
Run a workflow to audit every route under src/routes/ for missing auth checks.
For an explicit invocation, use:
/workflows run <prompt>Open /workflows to navigate background runs, or use /workflows status <id>, /workflows pause <id>, /workflows resume <id>, and /workflows stop <id>. Built-in entry points include /deep-research <question>, /adversarial-review <task>, /multi-perspective "<topic>" [angle …], /code-review [target], and /codebase-audit <scope> "<check>" …. Use /ultracode for standing exhaustive orchestration or /effort high for a lighter persistent setting.
What are this agent's strengths and limitations?
- Provides real parallel orchestration with as many as 1,000 subagents per run and a maximum concurrency of 16.
- Routes work by model tier, exact provider/modelId, and thinking level instead of forcing every task onto one model.
- Journaled resume reuses completed calls, while edited-script resume can preserve an unchanged cached prefix and avoid paying for a full rerun.
- Git worktree isolation gives editing agents separate branches and retains their worktrees by default for later merging.
- Exposes measured tokens, cost, throughput, and live progress, alongside verification, judge panels, completeness checks, and human checkpoints.
- The runtime is tied to Pi; no direct deployment path is documented for ChatGPT, Codex, Claude Code, or standalone OpenAI and Claude API services.
- Wide fan-out can multiply model usage and cost, and a run has no total token ceiling when neither tokenBudget nor a configured default is present.
- Orchestration scripts run in a restricted Node vm without Date.now(), Math.random(), require, import, filesystem access, or network access.
- Resume matching is positional: inserting, removing, or reordering an earlier agent() call invalidates cache reuse from that point forward.
- Subagents no longer load host extensions by default, so MCP bridges, browser tools, and other tools registered by those extensions are not automatically available.
- Persisted child sessions retain full transcripts and may store sensitive material read by an agent.
How does this agent compare with similar options?
The project explicitly maps itself to Claude Code dynamic workflows: both use code-mode orchestration, isolated subagent contexts, structured outputs, background execution, model selection, and resume. This Pi implementation additionally documents Git worktree isolation, measured cost accounting, an interactive /workflows TUI, deep research, and reusable quality helpers. It is not presented as a Claude Code extension, and the source does not document direct execution inside Claude Code.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pi Dynamic Workflows This agent | 88 · Good | Agent plugin / skillFree + model costs | ★ 590 | 9d ago | TypeScript | — |
| TAKT Workflow Orchestrator | 57 · Major gaps | CLIFree + model costs | ★ 1.4k | today | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| AgentLoom | 52 · Major gaps | — | ★ 169 | today | Python | OpenAI API |
| Fusion Software Factory | 71 · Some gaps | CLIFree + model costs | ★ 1.3k | 5d ago | TypeScript | Codex · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows per-agent tool allowlists and denylists, optional git-worktree isolation, approval checkpoints, pause/stop controls, documented persistence locations, token and cost reporting, and an explicit warning that retained transcripts may contain sensitive material. The license attributes both the current maintainer and original author. Deductions apply because ordinary agents do not appear to receive a least-privilege tool set by default, natural-language triggering can start background workflows, no redaction or encryption controls are shown for persisted content, and the full external impact of model/network calls and runs allowing up to 1000 agents with potentially unlimited budgets and timeouts is not gated by confirmation. The dependency surface is small and publishing uses tests, OIDC provenance, and ignore-scripts, but peer ranges are broad or wildcarded, development dependencies use latest, and actions are pinned only to major tags.
The README, package metadata, CI/release definitions, and supplied tests are internally consistent about installation, capabilities, isolation, tool policy, and failure behavior. Tests cover unknown-agent warnings, legacy-path warnings, worktree cleanup, and error history, while the documentation explains empty-output retries, null results, and the prominent all-empty warning. Dependency availability is deducted because the Pi peer packages require an external host and lack upper bounds, typebox is wildcarded, and several development packages use latest; the static evidence cannot establish availability of every routed provider or model.
The material clearly identifies code audits, refactors, research, and multi-perspective review scenarios and exposes model tiers, exact models, thinking levels, agent types, schemas, budgets, retries, concurrency, isolation, saved workflows, and project/global overrides. Triggering uses bounded-word matching, excludes identifiers and paths, and can be renamed or disabled; explicit commands, natural-language patterns, and standing effort controls have clear boundaries. Environment support includes legacy-directory fallback, configuration-free model selection, and cwd-aware overrides. No material static-source deficiency warrants a deduction.
The README is thoroughly organized around installation, operation, capability tables, commands, runtime APIs, configuration, persistence, recovery, and controls, with extensive examples and concrete pitfall guidance. The complete MIT text agrees with package metadata. Deductions apply because no separate FAQ or formal changelog is evidenced, naming has some legacy-path compatibility and several overlapping entry points, and the clear semantic version/tag release process is not accompanied by a migration history or compatibility policy. The author, contributor, and repository update path are identified, but no maintenance commitment, security contact, or verified organizational responsibility is shown.
Results are delivered into the conversation and remain usable through the progress panel, run navigator, structured schemas, saved workflows, cross-checking, and persisted full-result files. Parallel routing, journal replay, worktree isolation, and composable review patterns provide clear marginal value over a single-agent flow. Token/cost measurement, budgets, cache-retention guidance, retries, and avoidance of repeated calls address cost-benefit tradeoffs thoroughly. Full scores here concern the documented and source-supported product design only; this static assessment does not judge actual answer correctness or realized savings.
Core capabilities are corroborated across the README, package scripts, CI/release configuration, and tests for tool policy, isolation, history, failures, and compatibility paths. Generated capability documentation and release checks add traceability. Deductions apply because the supplied tests represent only part of the repository, and broad claims such as deterministic orchestration, deep-research quality, 1000-agent scale, and complete cost accuracy cannot each be traced to implementation or focused tests in the provided excerpts. Marketing claims and independently established facts are also not always explicitly separated.
- Runs may default to no token budget or per-agent timeout and permit a high total-agent ceiling; set tokenBudget, agentTimeoutMs, concurrency, and maxAgents explicitly in production use.
- A bounded natural-language keyword can authorize a background workflow; disable it or choose a dedicated trigger when automatic orchestration is unwanted, and add checkpoints before consequential phases.
- Persisted agent sessions and run JSON may retain source code, prompts, tool results, and other sensitive material; review retention, access permissions, and cleanup requirements before enabling persistence.
- Worktrees are retained by default and agents may inherit broad tools; define least-privilege tool allowlists for agent types and manage retained worktrees deliberately.
- Peer and development dependency ranges are broad; use a lockfile, review dependency changes, and rerun the release checks before upgrades.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * fix(compat): support Pi 1.4 host events and delivery tests by @QuintinShaw in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/260 * fix(prompt): preserve host prompt sections when arming workflows by @QuintinShaw in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/258 * fix(commands): reject saved workflows using host command names by @QuintinShaw in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/259 * feat(codemode): enable isolated builtin tools in workflow children by @okuuva in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/255 …View on GitHub ↗ -
Release notes excerpt
Highlights - Resume interrupted fan-outs with opt-in completed-sibling replay, avoiding redispatch of eligible completed calls. Prefix replay remains the default. (#246) - Expose structured workflow results for codemode and durable progress entries for RPC clients. (#250, #239) - Discover workflow tools on demand on capable Pi hosts, with active-tool fallback for older hosts. (#248) - Honor custom Pi configuration directories, safely capture explicitly loaded host sessions, and scope keyword activation to individual interactive requests. (#238, #232, #253) Compatibility notes …View on GitHub ↗ -
Release notes excerpt
What's Changed * fix(errors): classify Anthropic 'out of extra usage' as a provider limit by @codesoda in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/230 * fix(ui): label completed workflow status correctly by @acolomba in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/234 * fix(runtime): create children with the host Pi SDK by @acolomba in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/233 * fix(agent): preserve terminal provider errors across schema repair by @QuintinShaw in https://github.com/QuintinShaw/pi-dynamic-workflows/pull/236 …View on GitHub ↗