> ## 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="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.