Turn one request into a JavaScript orchestration script that fans work out across isolated agents, routes each task to the right Pi, Codex, or Claude Code harness and model, cross-checks the results, and returns one synthesized answer. Intermediate work stays in script variables instead of filling your chat context.

Built for codebase-wide audits, multi-perspective review, large refactors, and source-checked research—the jobs that are too broad for one agent and one context window.

Claude Code plugin

Install the marketplace and plugin in one shell line:

claude plugin marketplace add fish0710/dynamic-workflows@main && claude plugin install dynamic-workflows@fish0710

The plugin installs the dynworkflow CLI from npm, adds it to Claude Code's Bash PATH, and provides the namespaced /dynamic-workflows:dynworkflow-cli skill for running, monitoring, resuming, and diagnosing workflows. Start a new Claude Code session after installation, or run /reload-plugins in an existing session.

After the marketplace is registered, later installations only need:

claude plugin install dynamic-workflows@fish0710

Standalone runtime

The same workflow engine now runs outside a Pi conversation through the dynworkflow CLI. One command can start the long-lived runtime, run a workflow, and serve a local dashboard:

npm install -g @fish59fish/dynamic-workflows

dynworkflow serve ./audit.workflow.js \
  --executor codex \
  --args '{"scope":"src"}'

Codex and Claude Code mode does not require or load the Pi SDK. The Pi packages are optional peers and are loaded lazily only when a workflow selects --executor pi (or an individual agent() selects executor: "pi"). dynworkflow doctor reports each adapter independently.

Open the printed, token-authenticated loopback URL to inspect:

• the current phase and phase timeline;
• every agent's executor, model, state, usage, full input, output, and retained history;
• durable runs from an earlier process;
• pending human checkpoints; and
• pause, resume, stop, and delete controls.

The runtime is the sole owner of live child processes. Other CLI invocations discover it through a project-scoped descriptor and send control requests to that owner:

dynworkflow run ./audit.workflow.js --executor claude-code
dynworkflow list
dynworkflow show <run-id>
dynworkflow pause <run-id>
dynworkflow resume <run-id> --script ./audit-revised.workflow.js --attach
dynworkflow stop <run-id>

Without an active server, dynworkflow run owns the run locally and waits for it to finish. Add --ui to serve the dashboard for that run, or keep dynworkflow serve running so later commands can submit detached work. --json makes run, list, and status output machine-readable for Claude Code, Codex, shell scripts, or another agent host. list --json is a lightweight summary; show <run-id> --json returns full agent detail.

Run state, the completed-call journal, prompts, outputs, usage, and locks use the same crash-safe project namespace as the extension. Set DYNAMIC_WORKFLOWS_HOME or pass --state-dir to move that state out of ~/.pi/workflows:

dynworkflow serve --state-dir ~/.dynamic-workflows

The dashboard is loopback-only and uses a random bearer token; direct non-loopback binds are rejected. Use SSH port forwarding when the UI must be viewed from another machine. Workflow JavaScript is trusted input: the VM enforces deterministic orchestration for resume, but it is not a security sandbox. On Unix, durable state directories use mode 0700 and run files, backups, locks, logs, and descriptors use 0600, because they may contain full prompts and outputs.

See the standalone runtime guide for the command, HTTP/SSE, embedding, persistence, and adapter contracts.

Start in 30 seconds

pi install npm:@fish59fish/dynamic-workflows

Run /reload in Pi, then ask naturally:

Run a workflow to audit every route under src/routes/ for missing auth checks.

Pi writes and starts the workflow in the background. A live panel tracks progress while you keep working, and the final result is delivered back into the conversation automatically.

Keyword triggering is on by default: use the bounded word workflow or workflows in a message to arm workflow mode — the assistant then handles a request by fanning it out across agents, but still answers plainly if you're only asking about workflows (the trigger authorizes the tool, it doesn't force it). Or run /workflows run <prompt> explicitly. Identifier-like text and paths such as myworkflow, workflow_name, and src/workflow-editor.ts do not trigger. You can change the keyword with /workflows-trigger set pi-workflow or disable it with /workflows-trigger off.

How it works

1. Orchestrate — Pi writes a deterministic JavaScript workflow with agent(), parallel(), pipeline(), and phase().
2. Fan out — native Pi sessions and ephemeral Codex or Claude Code CLI agents run concurrently, optionally on different models or isolated git worktrees.
3. Verify and return — the workflow cross-checks findings, journals completed work for replay, and delivers one result.

The orchestration itself is plain JavaScript:

export const meta = {
  name: 'auth_audit',
  description: 'Find routes missing auth checks and verify the findings',
  phases: [{ title: 'Scan' }, { title: 'Review' }, { title: 'Verify' }],
}

phase('Scan')
const files = await agent('List every route file under src/routes/.', { tier: 'small' })

phase('Review')
const findings = await parallel(
  files.split('\n').filter(Boolean).map((file) =>
    () => agent(`Audit ${file} for missing auth checks.`, {
      tier: 'medium',
      isolation: 'worktree',
    }),
  ),
)

phase('Verify')
return await agent(
  'Synthesize and double-check these findings:\n' + findings.join('\n\n'),
  { tier: 'big' },
)

Why use it

• Real parallel orchestration — fan out up to 16 concurrent and 1000 total subagents from one orchestration script.
• Per-agent harness routing — run each call through native Pi, Codex CLI, or Claude Code CLI with executor, while choosing model independently inside that harness.
• Per-agent model routing — use small, medium, or big Pi tiers, or choose an exact model supported by the selected executor.
• Journaled continuation and revision — resumeFromRunId continues a paused or failed run under the same ID; forkFromRunId creates a new immutable revision from a completed run. Both replay the longest unchanged journal prefix, so only the first changed, new, missing, or unusable call and its suffix run live.
• Git worktree isolation — let parallel agents edit safely on throwaway branches with isolation: "worktree".
• Measured usage — report real tokens and cost from each subagent session; add run, phase, or agent budgets only when you want them.
• Visible background runs — track phases, agents, models, fresh/cache tokens, cost, and live tok/s from the progress panel or /workflows navigator.
• Quality patterns — compose verify(), judgePanel(), loopUntilDry(), and completenessCheck() instead of rebuilding review loops.
• Reusable workflows — save any run as a command and call saved workflows from other workflows.

Supported workflow capabilities

The installed extension generates this compact index from its executable capability contract. Read the workflow authoring guide or use the packaged workflow-authoring skill for constraints, lifecycle guidance, and adaptable examples; configured route and agent-type values remain environment-specific.

| Name | Classification | Signature | Options and defaults | | --- | --- | --- | --- | | agent | runtime-global | agent(prompt, options?) => Promise<string \| structured value \| null> | label: string (optional; default: derived from phase and call count)phase: string (optional; default: current phase)schema: plain JSON Schema (optional)executor: "pi" | "codex" | "claude-code" (optional; default: run default, then "pi")model: string (optional)tier: string (optional)isolation: "worktree" (optional)agentType: string (optional)timeoutMs: number | null (optional; default: run timeout; null disables)retries: number (optional; default: run retry count)required: boolean (optional; default: false) | | parallel | runtime-global | parallel(thunks) => Promise<Array<unknown \| null>> | — | | pipeline | runtime-global | pipeline(items, ...stages) => Promise<Array<unknown \| null>> | — | | workflow | runtime-global | workflow(savedName, childArgs?) => Promise<unknown> | — | | verify | runtime-global | verify(item: unknown, options?: { reviewers?: number; threshold?: number; lens?: string \| string[] }) => Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }> | reviewers: number (optional; default: 2)threshold: number (optional; default: 0.5)lens: string | string[] (optional) | | judgePanel | runtime-global | judgePanel(attempts: unknown[], options?: { judges?: number; rubric?: string }) => Promise<{ index: number; attempt: unknown; score: number; judgments: Array<{ score: number; reason?: string }> } \| undefined> | judges: number (optional; default: 3)rubric: string (optional; default: "overall quality and correctness") | | loopUntilDry | runtime-global | loopUntilDry(options: { round: (roundIndex: number) => unknown[] \| Promise<unknown[]>; key?: (item: unknown) => string; consecutiveEmpty?: number; maxRounds?: number }) => Promise<unknown[]> | round: (roundIndex: number) => unknown[] | Promise<unknown[]> (required)key: (item: unknown) => string (optional; default: JSON.stringify)consecutiveEmpty: number (optional; default: 2)maxRounds: number (optional; default: 50) | | completenessCheck | runtime-global | completenessCheck(taskArgs: unknown, results: unknown) => Promise<{ complete: boolean; missing?: string[] } \| null> | — | | retry | runtime-global | retry(thunk: (attempt: number) => unknown \| Promise<unknown>, options?: { attempts?: number; until?: (result: unknown) => boolean }) => Promise<unknown> | attempts: number (optional; default: 3)until: (result: unknown) => boolean (optional; default: accept first result when omitted) | | gate | runtime-global | gate(thunk: (feedback: string \| undefined, attempt: number) => unknown \| Promise<unknown>, validator: (value: unknown) => { ok: boolean; feedback?: string } \| Promise<{ ok: boolean; feedback?: string }>, options?: { attempts?: number }) => Promise<{ ok: boolean; value: unknown; attempts: number }> | attempts: number (optional; default: 3) | | checkpoint | runtime-global | checkpoint(prompt, options?) => Promise<unknown> | default: unknown (optional; default: true when no UI and omitted)headless: "default" | "abort" (optional; default: "default")kind: "confirm" | "input" | "select" (optional; default: "confirm")choices: string[] (optional)timeoutMs: number (optional) | | log | runtime-global | log(message) => void | — | | phase | runtime-global | phase(title, options?) => void | budget: number (optional) | | args | runtime-global | args: unknown | — | | cwd | runtime-global | cwd: string | — | | process | runtime-global | process: { cwd(): string } | — | | budget | runtime-global | budget: { total, spent(), remaining() } | — | | script | workflow-tool-input | script?: string | — | | name | workflow-tool-input | name?: string | — | | args | workflow-tool-input | args?: unknown | — | | background | workflow-tool-input | background?: boolean = true | — | | maxAgents | workflow-tool-input | maxAgents?: number = 1000 | — | | concurrency | workflow-tool-input | concurrency?: number | — | | agentRetries | workflow-tool-input | agentRetries?: number = configured value or 0 | — | | agentTimeoutMs | workflow-tool-input | agentTimeoutMs?: number = configured default or unbounded | — | | tokenBudget | workflow-tool-input | tokenBudget?: number = configured default or unlimited | — | | resumeFromRunId | workflow-tool-input | resumeFromRunId?: string | — | | forkFromRunId | workflow-tool-input | forkFromRunId?: string | — |

Built-in workflows

/deep-research <question>   source-checked web research with citations
/adversarial-review <task>  findings challenged by skeptical reviewers
/multi-perspective "<topic>" [angle …]
                            independent angles followed by synthesis
/code-review [target]       7 parallel review angles plus verification
/codebase-audit <scope> "<check>" …
                            parallel checks followed by cross-validation

/code-review defaults to the current working diff. It also accepts a git range, a file, or a GitHub PR number:

/code-review
/code-review HEAD~3..HEAD
/code-review src/foo.ts
/code-review 42

For an always-on exhaustive mode, use /ultracode; /effort high is the lighter standing option.

These same 5 patterns are also reachable by name without a slash command — Pi can recognize a decomposable request and run the matching curated pattern directly:

Do a deep-research on whether Bun's test runner is production-ready.

is equivalent to /deep-research "...". A saved workflow always wins over a built-in of the same name, on both the slash-command and natural-language paths — so saving your own code-review shadows the built-in one everywhere.

Commands and run control

Pi can manage background runs directly with the workflow_control tool instead of asking you to type a command. It supports list, status, pause, resume, and stop; resume continues only paused or failed runs in place under the same canonical run ID. Completed runs are immutable and are revised with the workflow tool's forkFromRunId, which creates a new run ID while preserving the source. Status output includes run state, revision lineage, current phase, agent counts, active labels, and recorded token total.

| Command | Purpose | | --- | --- | | /workflows | Open the interactive run navigator | | /workflows run <prompt> | Arm workflow mode for a prompt even when keyword triggering is off | | /workflows status <id> | Watch a run and print its result when complete | | /workflows pause\|stop\|rm <id> | Control or remove a run | | /workflows resume <id> | Continue a paused or failed run in place | | /workflows save <name> | Save the latest script as a reusable command | | /workflows-trigger off\|on\|status | Control automatic keyword triggering | | /workflows-trigger set <word>\|reset | Set or reset the trigger word | | /workflows-progress compact\|detailed\|status\|max <N> | Live-panel detail level (and max agents shown per phase in detailed mode) | | /workflows-models | Map model tiers and thinking levels | | /ultracode [off] | Toggle exhaustive automatic workflows | | /effort off\|high\|ultra | Set the standing orchestration effort |

In the navigator: ↑/↓ select · enter/→ open · esc/← back · p pause · x stop · r rerun from scratch · s save · q quit. A fresh rerun does not reuse the journal; use forkFromRunId for a cached completed-run revision.

Agent details use a compact summary by default: completed agents show their final result, while active agents show the prompt and two latest history events. Press enter to open the full syntax-highlighted pager. In the pager, use j/k or ↑/↓ for lines, PgUp/PgDn for pages, g/G for the ends, and t to toggle live tail mode.

Runtime reference

| Global | What it does | | --- | --- | | agent(prompt, opts) | Spawn an isolated subagent; optionally validate its result with JSON Schema | | parallel(thunks) | Run () => agent(...) thunks concurrently and preserve input order | | pipeline(items, ...stages) | Fan items through sequential stages | | phase(title, { budget? }) | Group work in the live view and optionally set a phase budget | | verify / judgePanel | Cross-check a result or choose the best candidate | | loopUntilDry / completenessCheck | Repeat discovery until no new findings remain | | workflow(name, args) | Run a saved workflow inline | | checkpoint(prompt, opts) | Add a journaled human-approval gate | | budget | Inspect real tokens spent and remaining |

| Agent option | Description | | --- | --- | | executor | Complete agent harness: pi (default), codex, or claude-code | | tier | small, medium, or big Pi model routing | | model | Exact model accepted by the selected executor; never changes the executor | | agentType | Named role, tool, and model definition | | isolation | Use "worktree" for conflict-free parallel edits | | schema | JSON Schema for a validated structured result | | label / phase | Display label and phase override | | timeoutMs / retries | Optional per-agent timeout and recoverable-failure retries | | required | After retries, throw an exhausted recoverable failure instead of returning null |

const plan = await agent("Diagnose the failing tests", {
  executor: "codex",
  schema: PLAN_SCHEMA,
})

const implementation = await agent(`Implement this plan: ${JSON.stringify(plan)}`, {
  executor: "claude-code",
})

return await agent(`Summarize the result: ${JSON.stringify(implementation)}`, {
  executor: "pi",
  schema: SUMMARY_SCHEMA,
  required: true,
})

Codex and Claude Code use fresh ephemeral CLI sessions. Completed results still participate in the workflow journal, but an incomplete external call restarts as a fresh process after resume. External executors keep the workflow cwd and role instructions but cannot receive Pi ToolDefinition, SharedStore, or agent-type tool-policy objects; pass intermediate data explicitly through return values. Claude Code runs in safe mode with a bounded coding-tool allowlist and automatic permission classification, never bypass-permissions mode.

The full documentation covers every option, structured output, determinism, saved workflows, and operational control.

Model tiers live at ~/.pi/workflows/model-tiers.json and accept Pi CLI-style thinking suffixes:

{
  "tiers": {
    "small": "openai-codex/gpt-5.4-mini:low",
    "medium": "openai-codex/gpt-5.4:medium",
    "big": "openai-codex/gpt-5.5:xhigh"
  }
}

Use /workflows-models to edit them interactively. Without a config, the extension ranks authenticated models by capability hints and assigns distinct models when possible.

Omitted tokenBudget and agentTimeoutMs values use configured defaultTokenBudget and defaultAgentTimeoutMs settings; without them, runs are unlimited and have no hard per-agent timeout. Add per-run or per-agent values when you need explicit gates. concurrency is clamped to 16; agentRetries retries only recoverable failures. Defaults live in ~/.pi/workflows/settings.json; defaultExecutor may be pi, codex, or claude-code and defaults to pi. defaultTokenBudget is a soft pre-call gate, and a project-level override of null cancels a global budget.

Pausing and resuming a run keeps the limits it started with — maxAgents, agentTimeoutMs, concurrency, and agentRetries carry over instead of falling back to defaults, and tokenBudget tracking is cumulative across the pause, so a run can't reset its spend by pausing and resuming.

Extension state lives outside the repository under ~/.pi/workflows:

• global settings and tiers: ~/.pi/workflows/settings.json and model-tiers.json
• project runs, journals, locks, and saved overrides: ~/.pi/workflows/projects/<project>/
• older project-local .pi/workflows/runs and .pi/workflows/saved remain readable as fallbacks

Subagents are in-memory by default. Set persistAgentSessions: true to retain full transcripts in Pi's standard session directory. This creates one file per agent and may store sensitive material that an agent read, so enable it deliberately.

Completed background runs persist their full result and replay journal in the project run JSON. The conversation delivery includes a pointer to that file when the visible summary is shortened. Use forkFromRunId to branch a completed run into a new immutable revision: unchanged journal entries replay for free in the revision's fresh usage ledger, while the source record remains unchanged.

Pi's /reload keeps the live workflow manager in-process when the installed extension version has not changed. Active background runs therefore continue streaming progress, remain controllable, and deliver their result through the freshly loaded extension; session-local /effort also survives the reload. If the package version changes, active runs are paused and a fresh manager loads, leaving them safely resumable through the journal instead of mixing extension versions. This handoff applies only to /reload. A process restart still uses the same durable journal path, recovering an interrupted running workflow as paused so it can be resumed safely.

Finished runs (completed, failed, or aborted) are retained in full on disk, capped at the 300 most recent per project — older ones are evicted first, and a running or paused run is never touched. Only a smaller number (20 by default) also stay fully loaded in memory for instant access right after they finish; older finished runs still show up in /workflows and workflow_control list, just read back from disk instead of memory. Library embedders can tune both caps — maxTerminalRunsInMemory on WorkflowManager and maxTerminalRunsOnDisk on the run-persistence layer.

Set a literal, case-insensitive custom trigger in ~/.pi/workflows/settings.json:

{
  "keywordTriggerWord": "pi-workflow"
}

The default workflow also matches workflows; a custom word matches exactly. Trigger words are case-insensitive and Unicode identifier-bounded, and do not activate inside paths, slash commands, or identifier-like text. Detection is purely textual, applied at submit time to the message you send — it does not depend on, or own, Pi's editor component, so it works the same regardless of what else is installed.

| Claude Code dynamic workflows | dynamic-workflows | | --- | --- | | Code-mode orchestration | JavaScript agent() / parallel() / pipeline() / phase() in a VM realm (for determinism, not a security boundary) | | Isolated subagent contexts | Fresh in-memory Pi sessions; results remain in variables | | Structured outputs | JSON Schema validation with bounded repair | | Background runs | Non-blocking run, live panel, and automatic result delivery | | Resume and revision | resumeFromRunId continues paused/failed runs under the same ID; forkFromRunId creates a new immutable revision from a completed run | | Model selection | Per-agent and per-phase routing across authenticated providers | | Ultracode | /ultracode or /effort ultra | | Additional Pi features | Worktree isolation, real cost accounting, deep research, and quality-pattern helpers |

Determinism and limits

Workflow scripts run in a Node vm sandbox. Date.now(), Math.random(), new Date(), require, import, filesystem access, and network access are unavailable inside the orchestration script. Subagents use their assigned tools; keeping the orchestrator deterministic is what makes journal replay reliable.

Journal replay applies both to same-ID continuation of paused/failed runs (resumeFromRunId) and immutable completed-run revisions (forkFromRunId). It matches cached results by positional call index (the order in which agent() and checkpoint() calls execute), the same contract Claude Code uses. The longest unchanged usable prefix replays; the first changed, new, missing, or unusable call and everything after it execute live. Inserting, removing, or reordering a call before others shifts their positions and invalidates the cache from that point on (mismatched calls simply re-run — no crash). To preserve the cached prefix, keep earlier still-good calls unchanged and in the same order.

Upgrading to 3.0

3.0 is a milestone release. The one behavior change to know about:

• Keyword triggering now authorizes the workflow tool instead of forcing it. In 2.x, typing the trigger word (default workflow) rewrote your message into a directive that forced a background workflow. In 3.0 it arms the tool and the model decides: a real, decomposable request is fanned out across agents, but a message that only mentions workflows — a question, a filename, a passing reference — is answered normally. Nothing to configure. If you relied on the word always kicking off a run, use /workflows run <prompt> for the explicit path. Keyword triggering stays on by default; /workflows-trigger off disables it and /workflows-trigger set <word> changes the word.

Everything else is additive or a fix: the workflow_control tool (list/status/pause/resume/stop), edited-script continuation for paused/failed runs, immutable completed-run forks, auto-resume on provider usage limits, and persistence/perf hardening. Requires pi ≥ 0.80.8.

Library API note: the unused createSharedStoreTools export was removed — use createAgentStoreTools.

Upgrading past 3.2

Two behavior changes to know about:

• Subagents no longer load host extensions by default. Each run now builds one shared, extension-free resource loader for all of its subagents (a memory-leak mitigation). Skills, prompts, and AGENTS.md context still load, and the coding tools and any toolset (e.g. web-research) you hand a subagent are unaffected. What subagents lose is host-extension-registered tools — MCP bridges, browser tools, or anything else another installed extension adds. If an agentType names one of those tools in its allowlist, that entry now matches nothing. This also means a subagent can no longer recurse into another orchestration extension, even one not covered by the existing tool denylist.
• Checkpoints persisted before this release re-run once. checkpoint()'s resume-identity hash now also covers default, headless, and timeoutMs, so changing any of them between runs correctly invalidates a stale cached answer. This is a one-time effect: any checkpoint cached under the old hash simply re-prompts once and then caches normally again.

Development

npm install
npm test     # Biome, TypeScript, unit tests, and release checks

Optional model-comprehension evidence

The comprehension harness is manual and never runs in normal CI, npm test, or the release gate. Select an available model explicitly; the harness never embeds or chooses from a static model or agent-type catalogue.

npm run comprehension -- --model provider/model                    # quick writing scenario
npm run comprehension -- --model provider/model --suite full       # write, edit, review, and debug
npm run comprehension -- --model provider/model --output runs/a.json
npm run delivery-choice -- --model provider/model                  # timing and token-budget choices

By default, evidence is written under ignored .pi/model-comprehension/. Each JSON run records the exact prompts and versions, generated workflows, skill reads, provider token usage, deterministic runtime calls/topology/results, assertions, and failure details. The delivery-choice harness also checks that ordinary requests omit tokenBudget and explicit user caps are preserved exactly. Scenario failures are retained as non-blocking evidence and do not produce a failing exit status; argument, model-selection, and setup errors do.

Features are also verified end-to-end against real Pi subagent sessions before release. See CONTRIBUTING.md to contribute.

Credits

This fork is derived from QuintinShaw/pi-dynamic-workflows and preserves the upstream MIT attribution. The code-mode orchestration idea comes from Michael Livs' original pi-dynamic-workflows and Anthropic's dynamic workflows in Claude Code. This project adds a host-neutral CLI runtime, model routing, journaled resume, worktree isolation, measured usage, an interactive UI, and built-in research and review workflows.

License

MIT — see LICENSE.