Dynamic Workflows

Use Claude Code's Dynamic Workflows to orchestrate dozens to hundreds of background sub-agents for repo-wide review, migration, and research — works through QCode

Need an API key? Sign up →·Endpoints & base URLs →

Subagents already let you "send out a clone" to investigate one thing in parallel. But when a task is big enough to need "a whole team" — say, sweeping an entire repository and writing a review for every module — a single subagent isn't enough. That's where Dynamic Workflows come in.

Dynamic Workflows let Claude Code orchestrate dozens to hundreds of background sub-agents in one shot, each taking a slice of the work and running in parallel, while you keep doing your own thing. It runs on whatever model Claude Code is currently configured with — so as long as you point Claude Code at QCode, workflows work out of the box.

What problem it solves¶

Ordinary subagents are great for "a few, controlled" parallel tasks: send 2–3 clones to check the API, the schema, and test coverage respectively. But some tasks are inherently highly parallel:

• Doing a per-file security/quality review across a repo of 200 files
• Batch-migrating an old API call to a new style across the entire codebase
• Around one theme, researching dozens of directories separately and summarizing

Done serially, you'd have to wait for Claude to grind through them one by one; spinning up dozens of subagents by hand means you split the tasks and babysit progress yourself. Dynamic Workflows hand the entire "split → distribute → run in background → summarize" loop over to Claude Code to orchestrate on its own.

How to trigger¶

Dynamic Workflows need no extra install, and triggering is lightweight:

• Include the keyword ultracode in your prompt; or
• Simply ask it to "run a workflow".

Once Claude Code recognizes the intent, it plans how many background sub-agents to dispatch and what each one owns, then starts running them in parallel.

> ultracode review every submodule under src/, focusing on error handling
> and input validation. Have each module output a short report, then roll
> everything up into one overview.

Or in plain natural language:

> Run a workflow for me: scan the whole repo for every call to the old
> httpClient, estimate the effort to migrate to the new fetch wrapper, and
> summarize grouped by directory.

Viewing runs with /workflows¶

The sub-agents a workflow dispatches keep running in the background — they don't block your main session, so you can keep asking other questions and keep writing code. To see which workflows are currently running and how far along they are, use:

/workflows

It lists the running and completed workflow runs, making it easy to track overall progress and inspect each sub-agent's output.

Background execution means big tasks no longer block your interaction. Fire off the instruction, go do something else, and come back to collect results with /workflows.

When to use a workflow vs a single subagent¶

The two are the same "parallel delegation" idea at different scales, and the choice is simple: it comes down to parallel scale and whether you need to background it.

Rule of thumb:

• Just a few subtasks and you want results right away → use subagents.
• Dozens or hundreds of subtasks that can run in the background → use Dynamic Workflows.

Dynamic Workflows are essentially the "scaled-up" version of subagents. Get comfortable with the subagents concept first, and workflows will feel natural.

Using it through QCode¶

Dynamic Workflows run on whatever model Claude Code is connected to and don't depend on any specific provider. That means once you point Claude Code at QCode, every background sub-agent a workflow dispatches goes through QCode's endpoints — the same API key starting with cr_ works throughout.

Minimal setup (Anthropic protocol):

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_key"

# Users in China should prefer the asia endpoint
# export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"

The BASE_URL must not have a trailing slash. Hitting that address directly returns 401, which is normal — it means the path is correct and only auth is missing.

Once configured, start Claude Code as usual and trigger a workflow with ultracode. For the full endpoint reference, the three domains (api / asia / us), and each protocol's paths, see Endpoints and API formats.

Every background sub-agent in a workflow is billed by the model you chose on QCode. A large workflow runs many sub-agents at once, so token consumption scales up accordingly — before a big run, it's worth doing a small-scope pilot with a flagship model (e.g. claude-opus-5, $5/$25 per million tokens, 1M context), confirming the output quality, and only then rolling it out fully.

Worked examples¶

Example 1: Repo-wide code review¶

Have the workflow produce one review per major module across the repo, with a unified focus and unified output, then roll them up:

> ultracode do an independent code review of every sub-package under packages/.
> Each review should cover: error handling, edge cases, any unhandled Promises,
> naming consistency. Each sub-package outputs a bullet list of no more than 20
> lines, then roll everything up into one master table sorted by severity.

Once dispatched, you can keep doing other things, check progress later with /workflows, and review the rolled-up table once all sub-agents finish.

Example 2: Large-scale API migration research¶

Before touching anything, use a workflow to map out the blast radius:

> Run a workflow for me: find everywhere in the codebase that uses axios
> directly, group by directory, estimate the effort and risk of switching to
> the in-project httpClient wrapper, and output a table of
> "directory / occurrences / migration difficulty / caveats".

With the full picture, you can decide the migration order based on real data instead of gut feeling.

Tips and caveats¶

• Start small, then scale: on your first run, scope the workflow to a single directory or package, verify the output format and quality meet expectations, then expand to the whole repo.
• Standardize the output format: spell out in the prompt what each sub-agent should "output, how long, and how to sort" — it saves a lot of effort at roll-up time.
• Background doesn't mean unattended: while a workflow runs you can do other things, but remember to come back and wrap up with /workflows.
• About images: Dynamic Workflows handle text/code tasks. If you want Claude Code to read images (screenshots, architecture diagrams, error screenshots), that's the vision-input capability and is unrelated to workflows; if you want to generate images, use gpt-image-2 image generation.
• To wire workflows into CI/scripts, combine headless mode with structured output — see Automation and CI/CD.

Triggers and key settings¶

As of 2026-10-15, according to the official Claude Code dynamic workflows documentation:

In /workflows, select a run and press s to save its script as a command of your own: saving to the project's .claude/workflows/ shares it with the repository, saving to ~/.claude/workflows/ keeps it to yourself.

Running workflows through QCode: points to note¶

• Concurrency and rate limits: a workflow can run 16 agents at once by default, while a QCode personal plan or Pay-as-you-go Pack allows 5 concurrent requests per API Key (10 on Ultimate; see FAQ). If a large run gets rate limited (commonly 429) or individual agents fail, first lower CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS to a value in line with your plan's concurrency and try again.
• Cost: the tokens of every agent are billed for the model you chose; QCode bills per token, with per-model rates at qcode.cc/models. The documentation says that when a run schedules more than 25 agents, or its projected total exceeds 1.5 million tokens, the task panel shows a Large workflow warning; it is advisory and does not pause the run. A trial on one directory or one narrow question is the safest start.
• Model: unless you specify otherwise, agents use the session's current model. For lightweight stages you can ask, when describing the task, for a lighter model such as claude-haiku-5-5.

Common errors and how to troubleshoot¶

FAQ¶

Can I continue after leaving the session?¶

Within the same session, yes: ask Claude to relaunch the same workflow; completed agents return their saved results, while failed ones and those that started after them run again. After exiting, claude --resume brings the session back and the run can be replayed; a freshly started session has no record of the earlier run.

How many agents can one run spawn?¶

The official limit is 1,000 agents per run, with 16 running at once by default. These are Claude Code's own limits; QCode's concurrency limit is separate, as described above.

Will a workflow be expensive?¶

It uses more tokens than doing the same work step by step in conversation. Try a small slice first, check each agent's token usage in /workflows, and stop the run at any time if needed.

Do the agents in a workflow follow my permission settings?¶

Yes. The documentation states that the agents' tool calls go through the same permission checks and sandboxing as any tool call in your session; the ultracode keyword only decides how the work is organized.

How do I let my team reuse a workflow?¶

In /workflows, select the run and press s, then save it to the project's .claude/workflows/ so it is shared with everyone through the repository.

Want to run large-scale workflows with a flagship model while keeping an eye on cost? Check out QCode pricing — one API key works across all endpoints.

Enterprise →