> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic workflows

Dynamic workflows let Qoder CLI run a structured multi-agent process in the background. Use them when a task needs phased execution, broad fan-out, cross-checking, or a repeatable process that should be visible while it runs.

A workflow moves the orchestration plan into a JavaScript script. The script decides which subagents to start, how to group work into phases, how to combine intermediate results, and what final output should return to the session.

<div id="when-to-use-workflows">
  ## **When to Use Workflows**
</div>

| Use      | Best for                                                                                  |
| :------- | :---------------------------------------------------------------------------------------- |
| Subagent | One focused side task where only the summary needs to return to the main conversation.    |
| Skill    | Reusable instructions, domain knowledge, or a process that the main agent should follow.  |
| Workflow | Repeatable orchestration across many subagents, phases, branches, or verification passes. |

Choose a workflow when the task is larger than a single agent call: repository audits, broad research, migration planning, release checks, cross-file sweeps, or review processes that need independent perspectives before a final answer.

<div id="what-workflows-do">
  ## **What Workflows Do**
</div>

| Capability                 | Description                                                                      |
| :------------------------- | :------------------------------------------------------------------------------- |
| Scripted orchestration     | Keep the loop, branches, phases, and intermediate state in a workflow script.    |
| Multi-agent fan-out        | Start multiple subagents for independent slices of work.                         |
| Phased execution           | Show progress through named stages such as scan, analyze, verify, and summarize. |
| Parallel or pipelined work | Run independent branches together, or move each item through staged processing.  |
| Background execution       | Continue using Qoder CLI while the workflow runs.                                |
| Reusable flows             | Save named workflows for project, personal, plugin, or built-in use.             |

<div id="run-a-workflow">
  ## **Run a Workflow**
</div>

Ask Qoder CLI to use a workflow in natural language:

```text theme={null}
Use a workflow to review this repository for security risks and summarize findings.
```

You can also ask for a saved or built-in workflow by name:

```text theme={null}
Use the deep-research workflow to investigate the tradeoffs of this architecture decision.
```

Qoder CLI may create a workflow for the current request, or use a saved workflow if one matches the task. When a dynamic workflow is generated, Qoder CLI shows the planned workflow before it runs. You can run it, view the raw script, reject with feedback, or cancel.

Workflows run as background tasks. After launch, Qoder CLI returns a workflow run ID and keeps execution progress available in the task UI.

<div id="deep-research">
  ## **Deep Research**
</div>

`deep-research` is a built-in workflow for questions that need broad web research, source comparison, and claim-level verification. Invoke it directly with a focused research question:

```text theme={null}
/deep-research Compare the security and operational tradeoffs of passkeys and passwords for a consumer web app in 2026.
```

If the request is too broad to research directly, Qoder CLI asks clarifying questions first and passes the refined question to the workflow.

The workflow runs five phases:

| Phase          | What happens                                                                                                                                                                                |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Scope**      | Decomposes the question into complementary search angles selected for the topic.                                                                                                            |
| **Search**     | Runs one Web Search agent per angle in parallel. Each agent ranks results against the original question and excludes obvious low-quality or irrelevant pages.                               |
| **Fetch**      | Deduplicates URLs, fetches relevant public pages, assesses source quality, and extracts concrete, falsifiable claims with supporting quotations.                                            |
| **Verify**     | Independent agents challenge the extracted claims. Claims that do not survive cross-checking are excluded, while claims that could not be checked are marked unverified instead of refuted. |
| **Synthesize** | Merges semantically equivalent claims, groups related findings, assigns confidence levels, and produces a cited report with an executive summary, caveats, and open questions.              |

The final report includes evidence, confidence, and source URLs for its findings. Claims that fail verification do not appear as findings. If an agent or network request fails before a claim can be checked, the report lists it as unverified rather than treating it as refuted.

Deep Research uses the Web Search and Web Fetch tools through its child agents. Authenticated, private, paywalled, or unavailable pages may not yield usable content. Because the workflow launches multiple agents and can consume tokens quickly, start with a specific question and narrow the time range, region, audience, or decision criteria when they matter.

<div id="monitor-workflows">
  ## **Monitor Workflows**
</div>

Use `/workflows` in the TUI to open the workflow task panel.

```text theme={null}
/workflows
```

From the panel, you can inspect running and completed workflow tasks, view status, phases, agents, logs, output paths, errors, and final results. `/tasks` also shows workflow tasks together with other background tasks.

When a workflow is running, the detail view lets you inspect individual agents. If an agent is still controllable, you can skip or retry that agent from the workflow detail view.

<div id="saved-workflows">
  ## **Saved Workflows**
</div>

Saved workflows let you reuse a known process by name. Qoder CLI discovers workflows from these locations:

| Scope    | Location                  | Use when                                                          |
| :------- | :------------------------ | :---------------------------------------------------------------- |
| Project  | `.qoder/workflows`        | The workflow belongs to the current repository or team.           |
| User     | `~/.qoder/workflows`      | The workflow is personal and should be available across projects. |
| Plugin   | Plugin-provided workflows | The workflow is shipped as part of a plugin.                      |
| Built-in | Qoder CLI built-ins       | The workflow is provided by Qoder CLI.                            |

Project workflows take priority over plugin and built-in workflows when names overlap. Use project workflows for team-owned processes that should travel with the repository, and user workflows for personal processes that should not be committed.

A saved workflow is a JavaScript file that starts with an exported `meta` object. The metadata gives Qoder CLI a name, description, phases, and optional usage hints or input schema.

```js theme={null}
export const meta = {
  name: "repo-audit",
  description: "Audit a repository area and summarize risks",
  whenToUse: "Use when the user asks for a structured repository audit",
  phases: [
    { title: "Scan", detail: "Find relevant files and areas" },
    { title: "Analyze", detail: "Run focused analysis agents" },
    { title: "Summarize", detail: "Merge findings into a final report" }
  ]
};
```

After saving it under `.qoder/workflows/repo-audit.js`, you can ask Qoder CLI:

```text theme={null}
Run the repo-audit workflow for the authentication module.
```

Saved workflows can receive input through `args`. Use `args` for target paths, issue IDs, research questions, options, or any other value that should change per run without editing the workflow script.

<div id="how-workflows-run">
  ## **How Workflows Run**
</div>

Workflow scripts are plain JavaScript. They can use workflow helpers such as `agent()`, `parallel()`, `pipeline()`, `phase()`, `log()`, `workflow()`, `args`, and `budget`.

1. Qoder CLI selects a saved workflow or creates a dynamic workflow for the task.
2. If review is required, Qoder CLI shows the workflow name, phases, script, and run options.
3. The workflow launches as a background task.
4. The script starts child agents and groups them into phases.
5. Intermediate results stay inside the workflow runtime instead of filling the main conversation.
6. Final output is written to the workflow run output and summarized back into the session.

Workflow runs store scripts, manifests, journals, transcripts, and output under the session directory in `.qoder/sessions`.

<div id="permissions-and-safety">
  ## **Permissions and Safety**
</div>

Dynamic workflows can run multiple subagents and may consume tokens quickly. Start with a narrow target when validating a large or expensive workflow.

Workflow scripts do not get direct access to your shell, filesystem, network, Node.js APIs, or MCP servers. Side effects happen through child agents, and those agents still go through Qoder CLI tools, permissions, hooks, and sandbox settings.

Use [Permissions](/en/cli/permissions) to control what workflow child agents can do, and [Hooks](/en/cli/hooks) to enforce organization-specific policy before or after tool calls.