Dynamic Workflows enables CodeBuddy to write a JavaScript orchestration script, where the runtime schedules dozens or even hundreds of subagents in the background to collaborate on completing tasks. The script itself is readable, editable, and rerunnable, making it suitable for codebase audits, large-scale migrations, and research tasks that require cross-validation.
Note:
Dynamic Workflows is currently in the research preview stage and requires CodeBuddy Code v2.105.0 or later. It is enabled by default. To disable it, turn off the "Dynamic workflows" toggle in /config.
A Dynamic Workflow is a JavaScript script that CodeBuddy writes on the fly for your task. The runtime executes it in the background while your session remains responsive. The script contains one or more agent() calls, each dispatching an independent subagent to work. After the script obtains intermediate results, it can branch, run tasks in parallel, or dispatch them to the next batch of subagents.
Use a Workflow when a task is too large to fit in a single session, or when you want the orchestration logic to be recorded as a "rerunnable script". Typical scenarios:
Interface contract / authentication / instrumentation inspection across the entire monorepo
Batch triage and ownership assignment for a group of issues
Cross-validation research across multiple repositories / multi-source materials
A solution worth drafting independently from multiple perspectives first and then comparing them to select the best one
This page introduces:
When to use a Workflow (choosing between subagents, Skills, and Agent Teams)
Run the built-in Workflow: /deep-research
Have CodeBuddy write a Workflow for your task, and save it for reuse.
How Workflows run and how to manage them
When to Use Workflow
|
Essence | Workers dispatched by CodeBuddy | Instructions that CodeBuddy follows | A leader supervises a group of peer sessions. | A script executed at runtime. |
Who decides what to do next | CodeBuddy, making decisions round by round | CodeBuddy executes as prompted. | Lead agent, making decisions round by round | Script. |
Where intermediate results are stored | CodeBuddy's context window | CodeBuddy's context window | Shared task list | Script variables. |
What is repeatable | Worker definition | The instruction itself | Team definition | The orchestration process itself. |
Scale | A small number of delegations per round | Same as subagents | Several peers handling long-running tasks | Tens to hundreds of agents per run. |
Interrupts | Start a new round. | Start a new round. | Teammates continue running. | Recoverable within the same session. |
Workflow moves the "plan" into code. For subagents / Skills / Agent Teams, CodeBuddy is the orchestrator. In each round, it decides who to dispatch next and what to do, with all results landing in the context window. In contrast, Workflow delegates loops, branches, and intermediate results to the script itself, leaving only the final answer in CodeBuddy's context.
Turning the plan into code has a second benefit: you can have the script apply a repeatable quality pattern instead of simply dispatching more agents. For example, you can have several agents perform adversarial peer reviews of each other's findings before reporting, or draft proposals from multiple perspectives simultaneously and then compare them to select the best one. The credibility of a single result will be much higher than that of a "one-pass" approach.
Running a Built-in Workflow
The fastest way to experience Workflow is to run /deep-research, a built-in "multi-source cross-validation research" workflow in CodeBuddy Code. During the session, you will see agents progressing in stages in the background, and when it finishes, you will receive a single synthesized report instead of a long chain of turn-by-turn conversations.
Step
1. Start a Workflow
Run /deep-research with a question you want to investigate. It searches, scrapes, and cross-validates sources from multiple angles in parallel, and finally synthesizes a report with citations.
/deep-research A comparison of the evolution of mainstream frontend monorepo tools (Turborepo / Nx / Lerna) in remote caching and task graphs over the past year
2. Approve and run
CodeBuddy Code will ask whether to allow this Workflow to run. Select Yes to continue. The specific prompt depends on your permission mode. 3. Monitor progress
The run starts in the background. Use /workflows to open the Workflows view, select the current run with the arrow keys, and press Enter to go to the progress page:
The progress page is organized by phases, with each phase showing the number of agents, total tokens, and elapsed time. Drill into any phase to view the prompts and outputs of each agent. You can also see a one-line progress summary directly in the task panel below the input box. Press the ↓ arrow key to move focus to the task panel, then press Enter to expand it.
4. Read the report
When the run finishes, the report is automatically returned to the session. Every claim is annotated with its sources, and claims that fail cross-validation are discarded.
To apply a Workflow to your own task, first have CodeBuddy write one. When a run produces satisfactory results, you can save it as a command.
Built-in Workflow
CodeBuddy Code includes the following Workflows:
|
/deep-research <question>
| Perform multi-angle parallel search, crawl and cross-verify sources, vote on each claim, remove parts that fail verification, and output a report with citations. WebSearch tool must be available. |
Workflows that you save are registered as commands in the same way and appear alongside built-in Workflows in / autocomplete.
Observing the Run
Workflows run in the background while the session remains responsive. At any time, /workflows can list active and completed runs. Select a run to go to its progress view.
The progress view is organized by phases, with each phase showing the number of agents, total tokens, and elapsed time. The status bar at the bottom lists all keyboard shortcuts:
|
↑ / ↓
| Select a stage or agent. |
Enter or →
| Drill down to the selected stage, and then drill down to the agent to view its prompt, recent tool calls, and final result. |
Esc
| Go back one level. |
j / k
| Scroll when agent details overflow. |
p
| Pause or resume the run. |
x
| Abort the selected agent; abort the entire Workflow when the focus is on the run. |
r
| Restart the selected running agent. |
s
| Save the script of the current run as a command. |
Using CodeBuddy to Write a Workflow
There are two ways to have CodeBuddy write a Workflow for your task:
Request a Workflow directly in your prompt: use natural language or the keyword ultracode, and CodeBuddy will write one for the task.
Let CodeBuddy decide on its own (ultracode mode): /effort ultracode sets the effort level to ultracode, and CodeBuddy will first plan every substantial task in the session as a Workflow.
You can also directly run an existing Workflow command, such as the built-in /deep-research or one you have saved.
Requesting a Workflow in a Prompt
If you don't want to change the overall effort level for the session and only want a specific task to run as a Workflow, add the keyword ultracode to your prompt. Saying "run this with a workflow" in natural language or using "use a workflow" has the same effect: CodeBuddy treats the direct request as an equivalent explicit opt-in.
ultracode: Scan all domains under packages/ to identify which Facade / CloudRepo methods lack unit tests, and sort them by risk.
CodeBuddy Code highlights keywords in your input. When CodeBuddy receives this prompt, it writes a Workflow script for the task instead of working through it turn by turn. If you do not want to trigger a Workflow, press Option+W on macOS or Alt+W on Windows / Linux to cancel the highlight for this prompt. Alternatively, place the cursor after the keyword and press Backspace to delete it. To disable keyword triggering entirely, go to /config and turn off "Ultracode keyword trigger".
If the run result meets your needs, you can save it as a command afterward.
If you already have an orchestrator built in another way, such as a subagent prompt folder or a task-dispatching Skill, you can have CodeBuddy review it and write an equivalent Workflow.
Ultracode Mode: Letting CodeBuddy Decide
Ultracode is a combined configuration in CodeBuddy Code: it pushes the reasoning intensity to xhigh and adds automatic Workflow orchestration. When Ultracode is enabled, CodeBuddy proactively determines which tasks are worth running as Workflows, without requiring you to remind it each time.
After ultracode is entered, a request may be split into multiple consecutive Workflows: one run to assess the current code, another run to implement changes, and another run to verify. In a session, every task runs in this pattern, and each request consumes significantly more tokens and takes longer than at lower effort levels.
ultracode takes effect only in the current session and is automatically reset when a new session starts. To return to everyday work, use /effort high to fall back. It is available only on models that support xhigh reasoning intensity. On unsupported models, the /effort menu does not show this option.
Approving the Plan Before Running
In the CLI, a pre-run confirmation is displayed at every startup:
Yes: Start running
Yes, and don't ask again this session: Start running and do not ask again about the Workflow tool in the current session (session-level only; a new session will ask again).
No: Cancel (you can also press Esc).
|
Default,Accept edits,Auto | Asks every time, unless you have selected Yes, and don't ask again this session in the current session. The entire prompt is skipped when ultracode is enabled. |
Bypass permissions,codebuddy -p,Agent SDK | Never prompts, and the run starts directly. |
The permission mode affects only the pre-launch prompt. Subagents dispatched by Workflow always run in acceptEdits mode and inherit your tool allowlist, regardless of the current mode of your session. File changes are approved automatically. Shell commands, Web Fetch, and MCP tool calls that are not in the allowlist may still trigger prompts during execution. To prevent long-running tasks from being interrupted, add the commands required by the agent to the allowlist before starting.
codebuddy -p and Agent SDK have no human-computer interaction entry. Tool calls are executed according to the permission rules you configure, without interactive confirmation.
Saving a Workflow for Reuse
When a Workflow is one you will run repeatedly (for example, a review process that must be performed on every branch), you can save its script as a command. In /workflows, select the run to keep, press s, and use Tab in the save dialog to switch between the two save locations:
Under the project, .codebuddy/workflows/: distributed with the repository and visible to everyone on the team.
The user directory ~/.codebuddy/workflows/: available in all projects and visible only to you.
Press Enter to save. You can then invoke it in any session with /<name>.
If a project-level Workflow and a user-level Workflow have the same name, the project-level one takes precedence.
Passing Parameters to a Saved Workflow
A saved Workflow receives input through args. In the script, it is a global variable named args. This way, you can pass research questions, a list of target paths, configuration objects, and more without modifying the script each time.
The following prompt triggers a saved Workflow and passes the issue list as a parameter:
Use /review-branch to run an architecture review on each of the latest 20 commits in feat/skills-center.
CodeBuddy passes the list as structured data, so the script can directly use array/object methods on args without parsing it. If the caller does not pass args, args in the script is undefined.
How Workflows Run
The runtime executes the script in an isolated environment, completely separate from your session. Intermediate results remain in script variables and do not enter CodeBuddy's context.
Each run writes the script to a file under the session directory (~/.codebuddy/projects/<session>/). CodeBuddy obtains this path when the run starts, so you can ask it "where is the script". Opening it allows you to read the orchestration logic written by CodeBuddy, diff it against the previous run, or edit it and have CodeBuddy restart with the edited version.
The runtime continuously records the results of each agent, which is the basis for run recovery within the same session.
Behaviors and Limitations
The runtime imposes the following constraints:
|
User input is not accepted during running. | The only thing that can pause a run is a permission request from the agent. If sign-off between stages is required, split each stage into a separate Workflow. |
Workflow itself does not have direct file system / Shell access. | File read/write and command execution are all performed by agents; scripts are only responsible for coordinating agents. |
Up to 16 concurrent agents at a time (fewer on machines with fewer CPU cores) | Limit local resource consumption. |
Up to 1000 agents per run. | Prevent uncontrolled script loops. |
Deterministic Sandbox
The runtime enforces determinism to prevent the same script from producing different results across two runs, which is also a prerequisite for resume cache hits. The sandbox rejects the following non-deterministic / arbitrary code generation APIs through compile-time scanning + runtime interception:
Time-related: Date.now(), new Date(), performance.now()
Random numbers: Math.random()
Arbitrary code generation: dynamic string evaluation and dynamic Function construction (the sandbox disables codeGeneration.strings)
Node globals: require / process / __dirname / Buffer are not visible in the sandbox.
When you need a timestamp or random number, use agent() to have a sub-agent fetch real information (search, read files, call APIs), encapsulating the uncertainty into the agent's result.
Script API
The script is a self-contained JavaScript module that can use the following global functions:
|
agent(prompt, options?)
| Dispatches a subagent to execute prompt; returns its result. options can specify tools / maxTurns / schema (structured output) / model, among others. |
parallel(items, options?)
| Fans out items in parallel, equivalent to Promise.all, but subject to a concurrency limit of 16. |
pipeline(items, options?)
| Runs sequentially, passing the result of each stage to the next; if any stage fails, the remaining stages return null. |
phase(name, body)
| Marks a segment of orchestration as a phase, and the progress view displays it aggregated by phase. body can be a synchronous or asynchronous function. |
log(...)
| Writes a timestamped log entry, which appears in the Run log of the progress view. |
args
| Arguments passed by the caller (see Passing Arguments to a Saved Workflow). |
workflow(name, args?)
| Nests a call to a saved Workflow (callable only by the parent; child levels no longer expose this hook, and deep nesting is prohibited). |
Run Management
Once a run starts, manage it from the /workflows view. You can also expand the progress row in the task panel below the input box.
Resuming a Paused run
If you stop a run, you can resume it: completed agents return cached results directly, and the remaining parts continue running. In /workflows, select the paused run and press p to resume it. You can also have CodeBuddy restart the run with the same script.
Resume is limited to the same CodeBuddy Code session. If you exit CodeBuddy Code while a Workflow is still running, the next session will start from the beginning.
Cost
A Workflow dispatches a large number of agents, so the Token consumption of a single run can be significantly higher than performing the same task through conversation. These consumptions are counted against your plan's quota.
To estimate costs before starting a large task, run it on a small slice first: a single directory instead of the entire repo, a specific problem instead of a broad topic. In the /workflows view, the Token usage of each agent is visible in real time, and you can press x at any time to stop a run without losing completed results. The runtime agent limit also caps the maximum cost a single run can consume, preventing runaway execution when a script is written incorrectly.
Each agent uses the current model of the session by default, unless the script explicitly routes a stage to a different model. You can control costs from several aspects:
Before a large task, check the current model with /model. If you usually switch to a cheaper model, remember to switch back or keep it.
When describing the task, proactively tell CodeBuddy: "Use a cheaper model for stages that do not require a high-performance model."
Disabling a Workflow
Workflow is available in the CLI, desktop app, IDE extensions, codebuddy -p non-interactive mode, and Agent SDK. The way to disable it is consistent across all forms. Disable it only for yourself:
In /config, turn off "Dynamic workflows". This change will be persisted to settings.
In ~/.codebuddy/settings.json, set "disableWorkflows": true. This change will be persisted.
Set the environment variable CODEBUDDY_DISABLE_WORKFLOWS=1. It is read at startup and takes effect wherever it is set.
To disable it for the entire organization: in Managed Settings, set "disableWorkflows": true. After it is disabled, the built-in Workflow commands become unavailable, the keyword ultracode is no longer triggered, and the /effort menu no longer displays the ultracode option.