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.

Deep Research

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:

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

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(), and args.

Qoder CLI selects a saved workflow or creates a dynamic workflow for the task.
If review is required, Qoder CLI shows the workflow name, phases, script, and run options.
The workflow launches as a background task.
The script starts child agents and groups them into phases.
Intermediate results stay inside the workflow runtime instead of filling the main conversation.
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, and hooks. Use Permissions to control what workflow child agents can do, and Hooks to enforce organization-specific policy before or after tool calls.