Dynamic Workflows

1. What Is a Dynamic Workflow?

A dynamic workflow is a JavaScript script that orchestrates many Claude Code subagents. Claude can write the script for the task you describe, and Claude Code runs it in the background while your main session remains responsive.

Workflows are especially useful for large audits, migrations, cross-checked research, and other tasks that are too large for one conversation to coordinate comfortably.

2. When Should You Use a Workflow?

The official documentation positions workflows for tasks where the orchestration itself benefits from being represented as code and rerun.

3. Typical Workflow Use Cases

• Codebase-wide bug sweep: inspect many files for the same class of problem.
• Large migration: transform hundreds of files in parallel.
• Cross-checked research: have independent agents investigate and verify claims.
• Iterative fixing: run a checker, fix failures, and repeat until the check passes or progress stops.
• Multi-angle planning: ask independent agents to develop approaches and compare them before choosing one.

4. Availability

Dynamic workflows are available on paid plans with Anthropic API access, and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry. On Pro, the feature is enabled from the Dynamic workflows row in /config.

5. The Built-in Workflow: /deep-research

Claude Code includes /deep-research as a bundled workflow for investigating questions across many sources.

/deep-research What changed in the Node.js permission model between v20 and v22?

The workflow can fan out research across several angles, fetch and cross-check sources, and synthesize a cited report.

Typical flow

1. Run /deep-research with your question.
2. Approve the workflow if Claude Code asks for permission.
3. The workflow runs in the background.
4. Use /workflows to watch progress.
5. Read the final report when the run finishes.

6. Watching a Workflow

Workflows run in the background, so your main session stays responsive.

/workflows

The progress view shows phases, agent counts, token totals, elapsed time, and individual agent results.

7. Ask Claude to Write a Workflow

You can explicitly ask Claude to use a workflow. The current documentation also supports the keyword ultracode.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

You can also simply say:

Use a workflow to audit every API endpoint under src/routes/ for missing auth checks.

Claude writes the workflow script for the task rather than solving the entire task turn-by-turn.

8. Where the Ultracode Keyword Works

The keyword is an opt-in trigger when it comes from human-entered input in supported interactive surfaces.

The current documentation notes that before v2.1.210 the keyword could trigger from these other routes too.

9. Dismiss or Disable the Keyword

If you did not mean to start a workflow, the current docs provide keyboard shortcuts to dismiss the highlight:

• macOS: Option+W
• Windows/Linux: Alt+W
• Or press Backspace while the cursor is immediately after the highlighted keyword.

You can also turn off the Ultracode keyword trigger from /config.

10. Let Claude Decide Automatically with Ultracode

ultracode can also be an effort level. It combines xhigh reasoning effort with automatic workflow orchestration.

/effort ultracode

Or start a session with:

claude --effort ultracode

With ultracode enabled, Claude decides when a substantive task warrants a workflow. A single request can produce several workflows, such as one for understanding the code, another for making the change, and another for verification.

11. Approving a Workflow Plan

In the CLI, the workflow approval prompt can offer:

• Yes, run it — start the run.
• Yes, and don't ask again... — remember approval for a bundled, saved, or plugin workflow in the project.
• View raw script — inspect the generated script first.
• No — cancel.

Ctrl+G opens the script in your editor, and Tab lets you adjust the prompt before the run starts.

12. Workflows in Non-Interactive Usage

For claude -p and Agent SDK usage, Claude Code does not display the interactive workflow approval dialog. The workflow tool call is evaluated through the same permission system used for other tool calls.

Possible ways to allow a workflow include permission rules such as:

Workflow

or a named saved workflow:

Workflow(workflow-name)

Other supported mechanisms include Auto permission mode, Bypass permissions mode, a PreToolUse hook, or host-side permission callbacks/tools.

13. Save a Workflow for Reuse

If a workflow performs a task you will repeat, save its generated script as a command.

/workflows

Select the run and press s.

After saving, the workflow runs as a slash command:

/workflow-name

14. Share a Workflow Through a Plugin

For distribution across teams or repositories, a workflow can be included in a Claude Code plugin.

plugin-root/
└── workflows/
    └── release-audit.js

Plugin workflows are namespaced by the plugin name. For example, a plugin named acme-tools with a workflow named release-audit can be invoked as:

/acme-tools:release-audit

15. Pass Input to a Saved Workflow

Saved workflows can accept input through the args parameter. This lets you reuse one orchestration script with different data.

Run /triage-issues on issues 1024, 1025, and 1030

The workflow can access the supplied structured value through the global args.

16. Workflow Script Structure

A saved workflow contains a meta block followed by a JavaScript script body.

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: {
    type: 'object',
    required: ['files'],
    properties: {
      files: {
        type: 'array',
        items: { type: 'string' }
      }
    }
  },
})

const audits = await pipeline(
  found.files,
  file => agent(`Audit ${file} for missing authentication checks.`, {
    label: file,
  })
)

return audits.filter(Boolean)

Main building blocks

17. Important Script Rules

• export const meta should be the first statement.
• The meta block should be a plain object literal with name and description.
• The workflow body is plain JavaScript with top-level await.
• The runtime does not allow module loading through import().
• phase(), log(), and args can be used in the body.
• If the body contains a syntax error, Claude Code reports it when the workflow is run.
• For repeatable relaunches, Date.now(), Math.random(), and no-argument new Date() are blocked inside the script.

18. How a Workflow Runs

The workflow runtime executes the script in an isolated environment separate from your conversation.

Intermediate results stay in script variables rather than filling Claude's main context. Each run's script is stored under the session's project directory in ~/.claude/projects/.

19. Prompt Caching in Fan-Out

Agents in the same workflow run can share prompt-cache prefixes when they use the same model, effort level, agent type, tools, output schema, and working directory.

The current runtime normally keeps a workflow agent's cache for five minutes. The subagentPromptCacheTtl setting can extend this to 1h. One-hour cache writes are billed at a higher rate.

20. Workflow Behavior and Limits

21. Resume a Workflow After a Pause

Paused workflows can be resumed from /workflows by selecting the run and pressing p.

For a stopped run, Claude can relaunch the workflow using the same script. Completed agents can return saved results, while failed or still-running work may be rerun according to the documented replay rules.

Workflow results are kept under the session's project directory. A resumed Claude Code session can replay those results when asked to relaunch the workflow.

22. Leaving Claude Code While a Workflow Runs

• If you background the session, the workflow can continue in the background.
• If Agent View is enabled and you exit, Claude Code can offer to move the run to the background.
• If you choose to stop tasks instead, the workflow stops with the session.

23. Cost and Token Usage

A workflow can spawn many agents, so it may use substantially more tokens than solving the same task directly in one conversation.

• Workflow runs count toward plan usage and rate limits.
• The /workflows view shows token usage as the run progresses.
• Test a large workflow on a small slice first.
• Use a smaller size guideline when you want fewer agents.
• The runtime's agent caps limit runaway growth.

24. Large Workflow Warning

By default, Claude Code shows a Large workflow warning when a workflow schedules more than 25 agents or its projected token total exceeds 1.5 million.

The warning is advisory: it does not automatically pause or limit the run.

25. Choosing the Workflow Size

A size guideline tells Claude how many agents to aim for when it writes a dynamic workflow.

The current default is medium on versions that support the size guideline.

/config workflowSizeGuideline=small

26. Model Selection

Claude Code selects each workflow agent's model using the same general ordering used for subagents. A model specified for a stage has priority at that invocation. Otherwise the session's model can be used.

For large runs:

• Check /model before starting.
• Use smaller models for simple stages when appropriate.
• Use stronger models for stages where deeper reasoning is valuable.

27. Example: Audit Hundreds of Files

Use a workflow to audit every route handler under src/routes/
for missing authentication checks, and adversarially verify each
finding before reporting it.

28. Example: Keep Fixing Until Tests Pass

Workflows can express repeated loops.

Use a workflow to run npx tsc --noEmit and keep fixing the
reported errors until the type check passes or two rounds in
a row make no progress.

The workflow can therefore encode:

29. Example: Large Migration

Use a workflow to migrate every component under src/components/
from JavaScript to TypeScript, working on each file in its own
isolated copy.

This pattern is useful because many files can be transformed independently while verification can happen after the transformations.

30. Example: Review Every Changed File

Use a workflow to review every file changed in this PR for
correctness issues, then merge the per-file findings into
one ranked summary.

The workflow can use one reviewer per file and then a final agent to rank and deduplicate the results.

31. Example: Research Across Many Sources

Use a workflow to research how our three competitors handle
rate limiting: read their public docs and recent changelog
entries in parallel, then compare the approaches.

This is the same general pattern behind the bundled deep-research workflow: fan out research, collect evidence, cross-check, and synthesize.

32. Example: Search Until No New Issues Appear

Use a workflow to find flaky tests in this repo: run the suite
repeatedly, record which tests fail intermittently, and stop
once two rounds in a row find nothing new.

This demonstrates that workflows are not limited to simple one-pass parallelism. They can encode stopping conditions and repeated rounds.

33. Best Practices

• Start small: test a workflow on one directory or a narrow question before scaling it.
• Separate independent work: fan out only when agents can make useful progress independently.
• Add verification: use independent reviewers when accuracy matters.
• Keep intermediate data in the script: let the main conversation receive the useful final result.
• Watch token usage: many agents can become expensive quickly.
• Save successful workflows: repeated orchestration should become a reusable command.
• Choose an appropriate size guideline: do not default to huge runs for small tasks.
• Use worktree isolation where edits could conflict: the workflow coordinates agents, but isolation remains important for parallel changes.

34. Common Mistakes

35. Editing a Saved Workflow

The current documentation recommends using the bundled /workflow-authoring skill before editing a saved workflow. That skill requires Claude Code v2.1.248 or later.

/workflow-authoring

After editing, use:

/reload-skills

to reload workflow directories before running the workflow again in the current session.

36. Quick Memory Map

37. Beginner Checklist

1. Ask: is the task large enough to benefit from multiple agents?
2. Decide whether subagents, Agent Teams, or a workflow fits better.
3. For a one-off workflow, ask Claude to “use a workflow” or use ultracode.
4. Review the generated plan when Claude Code asks for approval.
5. Run /workflows to watch progress.
6. Inspect token usage for large runs.
7. Verify important findings rather than trusting a single pass.
8. Save successful repeated workflows as commands.
9. Use args to make reusable workflows configurable.

38. Interview / Revision Questions

1. What is a dynamic workflow in Claude Code?
2. How is a workflow different from a subagent?
3. How is a workflow different from an Agent Team?
4. What does /workflows do?
5. What is /deep-research?
6. What does the ultracode keyword do?
7. What happens when /effort ultracode is enabled?
8. Where can a saved workflow be stored?
9. What is the purpose of args?
10. What are agent(), pipeline(), and parallel()?
11. What are the main workflow concurrency and total-agent limits?
12. Why can workflows consume more tokens than ordinary conversations?
13. What is the purpose of a workflow size guideline?

39. Practice Exercises

40. Final Takeaway

Dynamic workflows are Claude Code's way to turn complex multi-agent orchestration into executable, repeatable code. They are most valuable when the task is large, repetitive, parallelizable, or benefits from independent verification.