# pi-dynamic-workflows: Claude Code-style subagent orchestration for Pi > A TypeScript Pi extension that turns one prompt into a JavaScript orchestration script, fans the work out across routed subagents, and journals every agent so an interrupted run can resume without paying for the same tokens twice. **QuintinShaw/pi-dynamic-workflows** — Claude Code–style dynamic workflows for Pi: code-mode subagents with real model routing, journaled resume, git-worktree isolation, cost accounting, an interactive /workflows TUI, an /ultracode standing opt-in, and deep research. - Repository: https://github.com/QuintinShaw/pi-dynamic-workflows - Website: https://quintinshaw.github.io/pi-dynamic-workflows/ - Stars: 549 · Forks: 107 - Language: TypeScript - License: MIT - Published: 2026-09-20 · Updated: 2026-09-20 · Language: en - Canonical page: https://hysenlabs.com/projects/quintinshaw-pi-dynamic-workflows ## The context window is the problem pi-dynamic-workflows attacks Ask a single coding agent to audit every route under src/routes/ and the transcript becomes the bottleneck before the model does. Each file read, each intermediate finding, each dead end lands in one conversation, and by the time the agent reaches the last file it is reasoning over its own earlier noise. pi-dynamic-workflows takes the opposite position: the orchestration is a deterministic JavaScript script, and intermediate work stays in script variables instead of filling the chat context. The README frames the target audience directly, naming codebase-wide audits, multi-perspective review, large refactors, and source-checked research as "the jobs that are too broad for one agent and one context window." That is a narrow but real slice of work. If your task fits in one turn, this is the wrong shape of tool, because you pay for a script and a fleet where a single prompt would do. ## How a prompt becomes a routed, journaled agent fleet The mechanism is a script Pi writes on your behalf. You supply a request in natural language; Pi produces a JavaScript module that exports a `meta` object and then calls runtime globals to do the work. Three primitives carry the structure: `agent()` runs one subagent and returns its output, `parallel()` takes an array of thunks and runs them concurrently, and `pipeline()` threads items through stages. `phase()` marks progress boundaries that the TUI reports against. The README's own example shows the shape: a `small` tier agent lists route files, a `parallel()` fan-out audits each file at `medium` tier with `isolation: 'worktree'`, and a final `big` tier agent synthesizes and double-checks the findings. Routing is explicit. You pass a `tier` of `small`, `medium`, or `big`, or name an exact model with `thinking` set to one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Isolation is opt-in per call: `isolation: 'worktree'` puts each parallel agent on its own branch, and `keepWorktree` defaults to true so the branches survive for merging. The README states the ceiling as up to 16 concurrent and 1000 total subagents from one script. ## Installing pi-dynamic-workflows and running a first audit Installation is one command against the npm package, followed by a reload inside Pi. The README gives this sequence. ```bash pi install npm:@quintinshaw/pi-dynamic-workflows ``` After the install completes, run `/reload` in Pi so the extension is picked up. From there you can either ask naturally or invoke the command explicitly. The README shows the natural-language path, and it is worth quoting the phrasing because the trigger is a bounded keyword rather than a mode you toggle. ```text Run a workflow to audit every route under src/routes/ for missing auth checks. ``` Pi writes the workflow and starts it in the background. A live panel tracks progress while you keep working, and the result is delivered back into the conversation. If you would rather not rely on the keyword, the explicit form is `/workflows run `. You can change the trigger word with `/workflows-trigger set pi-workflow` or turn it off entirely with `/workflows-trigger off`. Note what the trigger does and does not do: the README says it authorizes the tool rather than forcing it, so asking a question about workflows still gets you a plain answer. Identifier-like text such as `myworkflow`, `workflow_name`, or `src/workflow-editor.ts` does not arm it. ## Journaled resume and edited-script replay are the real differentiators Long fan-outs fail. A run gets interrupted, a model call times out, or you notice one prompt in the middle of the script was badly worded. The README describes two recovery paths that are more interesting than the parallelism itself. The first is plain journaled resume: completed agents replay from cache after an interruption instead of rerunning and spending their tokens again. The second is `resumeFromRunId` with an edited script. Unchanged `agent()` calls replay from cache and only edited or new calls re-run, so fixing one bad prompt does not mean paying to re-run the entire workflow. That is the feature that changes how you work, because it makes iteration on a script cheap. Cost accounting backs it up: the tool reports real tokens and cost per subagent session, and the progress panel and `/workflows` navigator show phases, agents, models, fresh versus cache tokens, cost, and live tok/s. Budgets are opt-in at run, phase, or agent level, which is a sensible default. The documentation does not describe what happens to a run's journal when the orchestration script changes in a way that reorders or renames calls, so treat cache-key semantics as something to confirm against your own run before trusting it. ## Where it is the wrong tool, and what to use instead Two failure modes stand out. The first is scale mismatch: for a single-file change or a question answerable in one turn, the orchestration script is pure overhead. You spend a model call writing JavaScript, then pay for subagents to do what one prompt would have done. The second is determinism as a constraint rather than a benefit. Because the workflow is a script, the tasks you can express are the ones you can enumerate. Exploratory debugging, where each step depends on what the last step revealed and you cannot write the fan-out in advance, fits a plain interactive agent session better. The README's own framing supports this: the named use cases are all breadth tasks with a known shape. If you want the comparison in one line, a single-agent session is a conversation that adapts, and pi-dynamic-workflows is a program you write once and replay. The tool also assumes Pi as the host. The README points at pi.dev for the package listing, and the extension is built for Pi, so if your team is standardized on a different coding agent, this is not a drop-in. The related searches around "Claude dynamic workflows" are worth reading carefully here: the project is Claude Code-style, not Claude Code, and the README describes it as built for Pi. ## Maintenance, licence, and what staying current costs The repository is not archived, and the last push was on 2026-09-14, with v3.12.0 tagged the same day and v3.11.0 two days earlier. That is a fast release cadence, and it cuts both ways. You get fixes quickly; you also inherit churn. The package publishes a `release:check` script that chains `build`, `docs:check`, `context:check`, `test:unit`, and `release:verify`, and the README's capability table is generated from an executable capability contract rather than hand-maintained. That is a good sign for documentation drift, since the table cannot silently disagree with the code. The flip side is that the capability contract is the source of truth, so anything not in it is not a supported surface. Licence is MIT, which permits commercial use and modification with the copyright notice retained; that is a summary of the identifier, not legal advice, and your counsel should read the LICENSE file. Upgrade cost is the part the README does not document: it says nothing about a migration path between major versions or a deprecation policy for the runtime globals, so pinning a version and reading the release notes before bumping is the honest approach. ## Conclusion Adopt it if your work is broad enough that one context window is the bottleneck: route audits, multi-perspective review, large refactors, source-checked research, and you already run Pi. Do not adopt it for a single-file edit or a question you can answer in one turn, because writing an orchestration script costs more than the task. Before you commit, verify three things: that `pi install npm:@quintinshaw/pi-dynamic-workflows` resolves against your Pi version, that your configured route and agent-type values exist in your environment (the README says they remain environment-specific), and that worktree isolation behaves as you expect on your repository, since the default keeps worktrees for merge rather than deleting them. ## FAQ ### What is a dynamic workflow in pi-dynamic-workflows? Pi writes a deterministic JavaScript orchestration script using `agent()`, `parallel()`, `pipeline()`, and `phase()`, runs subagents concurrently, cross-checks the results, and returns one synthesized answer. Intermediate work stays in script variables rather than in your chat context. ### What is Pi in software development, and does pi-dynamic-workflows require it? The project is a Pi package built for Pi, listed on pi.dev, and installed through the `pi` command. The README does not describe running it outside Pi, so Pi is a prerequisite rather than an optional host. ### Is there a Python workflow package available for pi-dynamic-workflows? The project is written in TypeScript and distributed as an npm package, and the README describes no Python interface. The orchestration scripts you write are JavaScript modules. ## Sources - [License: MIT](https://github.com/QuintinShaw/pi-dynamic-workflows/blob/main/LICENSE) - [Project website](https://quintinshaw.github.io/pi-dynamic-workflows/) - [QuintinShaw/pi-dynamic-workflows on GitHub](https://github.com/QuintinShaw/pi-dynamic-workflows) - [README](https://github.com/QuintinShaw/pi-dynamic-workflows/blob/main/README.md) - [Releases](https://github.com/QuintinShaw/pi-dynamic-workflows/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/quintinshaw-pi-dynamic-workflows