Imagine you need to process 210 files at once: review code, extract metadata, generate reports. Doing this in sequence would take hours. With a dynamic workflow, the orchestrator launches one subagent per file — all at the same time, each in its own window — and you get the consolidated results in minutes. The diagram below shows what happens under the hood.
Detailed content
🌐 What a dynamic workflow is
In Claude Code, a dynamic workflow is an orchestration where the
the number of subagents isn't fixed in the prompt — it is determined at
runtime by the orchestrator. The orchestrator receives the list of items, decides how many agents it will need,
and launches them all via Task tool, one for each item.
What it is
An execution structure where the orchestrator dynamically generates N parallel tasks based on the input — whether it’s a list of files, a list of URLs, a list of chapters, or any iterable collection. Each item becomes an independent subagent.
Why learn
Understanding dynamic workflows is what lets you run jobs that would be impossible to complete sequentially within a single session. It’s the difference between processing 5 files and processing 200 — with the same prompting effort. Without this knowledge, you underuse the platform’s most powerful tool.
Key concepts
🚀 The trigger: from "workflow" to ultracode
The magic word has changed. For a long time, the standard prompt for activating large-scale orchestration was
workflow. With the latest versions of
Claude Code, the recommended trigger has become ultracode.
The behavior is the same—but the token changed. Knowing this prevents frustration when you follow older tutorials.
What it is
ultracode is an instruction to the orchestrator
to use the maximum available parallel capacity. When you include this token in the prompt, the conductor knows it
can (and should) launch as many subagents as needed, without artificial constraints.
Why learn
The right token changes the model’s execution strategy. Without it, Claude may choose to process sequentially or with fewer agents. With it, you explicitly declare: "use massive orchestration here." It’s the switch between normal mode and full-scale mode.
Key concepts
ultracode
workflow
📈 Scale: dozens and hundreds of agents
Claude Code was designed to support orchestration in real scale. We’re not talking about 3 to 5 subagents—we’re talking about dozens to hundreds running in parallel. Each subagent has its own session, uses tokens independently, and can be a different model from the orchestrator.
What it is
The platform doesn’t impose a hard limit on the number of subagents per workflow. The practical limit is your API account (rate limits), the available budget, and your ability to consolidate results without blowing up the orchestrator’s context. Jobs with 40+ simultaneous agents are common in large-scale audit scenarios.
Why learn
Knowing the possible scale changes your prompt architecture. If you don’t know you can launch 100 agents, you’ll keep designing sequential solutions for problems that can be parallelized. Knowing the real ceiling lets you design the right workflows from the start.
Key concepts
💸 Cost and session limit
Dynamic workflows are expensive by design. Each subagent consumes tokens independently — and the cost of a workflow with 200 agents is approximately 200× the cost of a single agent running the same task. In addition to the financial cost, there's the session limit: the orchestrator still needs enough context to read all the reports.
What it is
The cost of a workflow is the sum of each subagent’s tokens plus the orchestrator’s tokens when consolidating. The orchestrator needs context to receive the reports — if each agent returns 500 tokens and you have 200 agents, that’s 100 000 tokens just for the reports, before any analysis.
Why learn
Planning costs before execution prevents surprises. A poorly sized workflow can consume the entire monthly budget in minutes. Understanding the cost structure lets you decide: is it worth using Haiku for subagents? Is it worth asking for ultra-short summaries? Is it worth splitting work into smaller batches?
Key concepts
- • Use Haiku for subagents when possible
- • Ask for a short summary (not a raw dump)
- • Process in batches of 20–40 at a time
- • Test with 5 items before scaling up
- • Ask for long output from each agent
- • Use Opus for all subagents
- • Launch 200 agents without testing first
- • Ignore the consolidation cost
🔬 The real case: 41 and 210 subagents
Two numbers became benchmarks in the Claude Code community for real-world workflows at scale: 41 subagents (codebase audit case) and 210 subagents (mass document processing). These aren’t tool limits — they’re documented cases that prove the architecture supports scaling without structural failures.
What it is
Each subagent analyzed a different module. The orchestrator consolidated the findings into a single security report.
Each subagent processed one section of a large document. Full fan-out in a single call to the orchestrator.
Why learn
These cases prove that dynamic workflows aren't theory—they're practice. They also set a scale threshold: if your problem has fewer than 40 parallel items, you're well within the comfort zone. If it has more than 100, you need explicit cost planning.
Key concepts
✅ When dynamic workflows are worth using
Not every parallel job needs a dynamic workflow. The rule of thumb: if processing each item is independent, the list has more than 10 items e the context would explode if processed sequentially — that’s when dynamic workflows are the right choice.
What it is
The decision criterion has three dimensions: independence (the items don’t depend on one another), volume (a list long enough to justify the orchestration overhead), and context risk (processing everything in the lead agent would overwhelm the context window).
Why learn
The most common mistake is using a workflow for everything — including small jobs where a sequence would be more efficient and less expensive. Learning the right criteria prevents wasted tokens and unnecessary complexity.
Key concepts
- • Review 20+ code files
- • Process sections of a long document
- • Generate a report for N repositories
- • Analyze N contracts in parallel
- • Translate N pages simultaneously
- • Job with 2–3 items (a sequence is enough)
- • Items that depend on one another
- • When the cost outweighs the time savings
- • Creative tasks that need coherence
- • Pipeline with shared state
⚠️ Cautions: what can go wrong
Large-scale orchestration brings risks that don't exist with simple jobs. The three most critical: context explosion in the consolidator, unexpected cost e silent failures — a subagent that returns nothing without notifying you.
What it is
Each risk has a specific cause: the orchestrator receives reports that are too large (context explosion); the model has no advance view of the total cost before execution (financial surprise); a subagent freezes or returns a silent error, contaminating the consolidated report without the orchestrator noticing.
Why learn
Workflows that fail silently are the most dangerous—the orchestrator delivers an incomplete report without indicating that 3 of the 40 subagents returned nothing. Understanding the risk lets you add explicit validation instructions to the orchestrator prompt.
Key concepts: mitigations
Conceptual example
Below is the mental model for a workflow to process 15 chapters of a technical book in parallel. Notice that the orchestrator doesn’t need to read all 15 chapters—each agent reads its own and returns only the essentials.
ORQUESTRADOR recebe: lista de 15 capítulos
PARA CADA capítulo em paralelo (ultracode):
SUBAGENTE recebe: "Leia capitulo_X.md e me traga:
1. Tese central (1 frase)
2. Principais conceitos (3 bullets)
3. Pontos confusos para revisão (máx 2)
Resposta: máx 100 tokens."
ORQUESTRADOR consolida: 15 resumos → relatório final
→ identifica capítulos com mais pontos confusos
→ sugere ordem de revisão prioritáriaDesign key: each subagent returns a maximum of 100 tokens. With 15 agents, the orchestrator receives ~1 500 tokens of input — manageable. Without this limit, 15 long chapters could return 50 000 tokens and blow up the context.
Ready-made prompts (copy and paste)
Three prompts to activate dynamic workflows with cost controls. In each one, notice the pattern: state the volume, limit each agent's output e request validation in the consolidated version.
Use ultracode para auditar os arquivos em src/.
Para cada arquivo, abra um subagente com Haiku.
Cada subagente deve retornar APENAS:
- Arquivo: nome
- Problemas: lista de até 3 items
- Severidade: baixa/média/alta
Máximo 80 tokens por resposta.
Ao final, consolide quantos arquivos retornaram
vazio e liste os de severidade alta primeiro.Tenho 80 contratos em /docs/contratos/.
ANTES de rodar, estime quantos subagentes serão
criados e o custo aproximado se cada agente usar
~2 000 tokens.
Se aprovado, use ultracode: abra um subagente por
contrato, extraia só: partes, valor total, cláusula
de rescisão. Resposta máx 60 tokens cada.
Relatório final: tabela resumida.Tenho 200 URLs em urls.txt. Processe em LOTES
de 20 URLs por vez (não todas de uma vez).
Cada lote: use ultracode, abra 20 subagentes em
paralelo, cada um faz: título + resumo em 2 linhas.
Após cada lote, mostre progresso (lote X/10 concluído).
Ao final, consolide tudo em uma lista numerada.Simulated screen: workflow running 6 subagents
This is what an audit workflow looks like in the Claude Code terminal: the orchestrator launched 6 agents simultaneously, each in its own session. The orchestrator's status line shows only ~8% of context used — the heavy work stayed with the subagents.
Exercise: workflow or sequence?
For each scenario below, decide: dynamic workflow or sequential processing? Justify your answer based on the three criteria: independence, volume, and context risk.
Review 3 configuration files to check whether environment variables are exposed.
Tip: think about the volume and orchestration overhead.
Generate a summary of 50 scientific papers for a literature survey. Each paper is ~10,000 words.
Tip: what happens to the context if you process in sequence?
Refactor a large module in stages: first extract classes, then rename variables, then add tests.
Tip: think about the dependency between the steps.
Evaluation criterion
A — Sequential: only 3 files; workflow overhead isn't justified. The cost and complexity outweigh the benefits of parallelism.
B — Dynamic workflow: 50 independent articles, each with 10k words. Processing them sequentially would blow up the context. Fanning out to 50 agents with short summaries is the right solution.
C — Sequential: the steps are dependent (you can't rename before extracting). Parallelism doesn't apply to pipelines with state dependencies.
✅ Module summary
- ▸ Dynamic workflow = an orchestrator launches N subagents based on the input—N is determined at runtime.
- ▸ The current trigger token is
ultracode(it was "workflow" in older versions). - ▸ The platform supports dozens to hundreds of simultaneous agents—the practical limit is the budget.
- ▸ Cost = total tokens from all subagents + consolidation. Calculate before running.
- ▸ Reference cases: 41 agents (audit) and 210 agents (document processing).
- ▸ Use when: independent items + high volume + risk from sequential context.
- ▸ Mitigations: short output per agent, test with a small batch, validation by the consolidator.