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.

When to Use Workflows

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.

What Workflows Do

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.

Run a Workflow

Ask Qoder CLI to use a workflow in natural language:

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:

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.

Monitor Workflows

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

/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.

Saved Workflows

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.

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:

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.

How Workflows Run

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.

Permissions and Safety

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 to control what workflow child agents can do, and Hooks to enforce organization-specific policy before or after tool calls.