Skip to content

Workflows ​

A workflow is a JavaScript script that orchestrates multiple subagents: what runs in parallel, what runs in sequence, what retries and when — decided by code, not improvised by the model.

When to reach for one ​

"More subagents" is not the criterion. The real question is whether control flow should be decided by code or by the model:

Use a workflowDon't
Covering a known set exhaustively (review 20 files, one each)A one-off exploratory task
Several independent perspectives, then a synthesis (three reviewers, majority wins)Something one subagent can answer
Scale beyond a single context (a repo-wide migration)Tightly coupled steps where you can't know step N+1 without seeing step N

It can spend a lot

A workflow may dispatch dozens of subagents. A spend warning is shown by default; you can disable it with skipWorkflowUsageWarning in settings, but think first about whether the run is worth it.

What a script looks like ​

It must begin with export const meta = {...}, and that must be a pure object literal — no variables, function calls, spreads or template interpolation (it has to be statically resolvable before anything runs).

js
export const meta = {
  name: 'review-changes',
  description: 'Review changes across dimensions; verify each finding independently',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}

const DIMENSIONS = [
  { key: 'bugs', prompt: 'Look for correctness problems…' },
  { key: 'perf', prompt: 'Look for performance problems…' },
]

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
  review => parallel(review.findings.map(f => () =>
    agent(`Adversarially verify: ${f.title}`, { phase: 'Verify', schema: VERDICT })
      .then(v => ({ ...f, verdict: v })))),
)

return { confirmed: results.flat().filter(Boolean).filter(f => f.verdict?.isReal) }

Available functions ​

FunctionWhat it does
agent(prompt, opts?)Dispatch a subagent. Without schema it returns the final text; with one, structured output is enforced and you get the validated object
parallel(thunks)Run concurrently. This is a barrier — it waits for all of them
pipeline(items, ...stages)Each item runs all stages independently; no barrier between stages
phase(title)Start a new phase; subsequent agent() calls group under it
log(msg)Emit a progress line
workflow(name, args?)Run another workflow inline (one level of nesting only)
argsThe JSON value passed in from the Workflow tool

agent() options: label (display name), phase (grouping), schema (JSON Schema, forces structured output), model, effort, isolation: 'worktree', agentType.

pipeline is the default; parallel is the exception ​

This is the easiest thing to get wrong. parallel is a barrier: nothing downstream moves until the slowest one finishes.

js
// Don't do this — that middle transform doesn't need a barrier
const a = await parallel(...)
const b = transform(a)          // just flatten/map/filter
const c = await parallel(b.map(...))

A barrier is only correct when stage N genuinely needs all of stage N−1 — deduplicating across the whole result set, say, or bailing out entirely if nothing was found. Otherwise use pipeline: item A can be in stage 3 while item B is still in stage 1.

Limits ​

ValueNotes
Concurrencymin(16, CPU cores − 2)Excess queues; nothing is dropped
Items per parallel/pipeline call4096Exceeding it is an error, not a silent truncation
Total subagents per workflow1000Runaway backstop

"Not a silent truncation" is deliberate: truncation makes you believe you covered everything when half of it was skipped — far harder to diagnose than an error.

Scripts are deterministic ​

Inside the sandbox, Date.now(), Math.random() and no-arg new Date() are deleted — calling them throws. import() is unavailable too.

The reason is resume: resumeFromRunId relies on "same script + same args = same call sequence" to know which agent() results can be reused from cache. One source of randomness or time dependence and that premise is gone.

Need a timestamp? Pass it in via args, or stamp results after the workflow returns.

Resume ​

Every run returns a runId. Re-invoking with Workflow({ scriptPath, resumeFromRunId }): the longest unchanged prefix of agent() calls returns cached results instantly; the first edited call and everything after it runs for real.

So iterating on a script doesn't mean paying for the whole thing again — which is exactly why the determinism rule above exists.

Three ways to invoke ​

Workflow({ script: "..." })                // inline script
Workflow({ name: "review-changes" })       // predefined: project .deepcode/workflows/ first, then ~/.deepcode/workflows/
Workflow({ scriptPath: "/path/to.js" })    // script on disk, highest precedence

Every invocation persists its script under the session directory and returns the path — iterate by editing that file and re-running with scriptPath instead of resending the whole script.

Orchestration patterns worth knowing ​

  • Adversarial verification — spawn N independent skeptics per finding, each prompted to refute it; kill it if the majority do. This is what catches plausible-but-wrong conclusions.
  • Perspective-diverse verification — when a finding can be wrong in several ways, give each verifier a distinct lens (correctness / security / performance / does-it-reproduce). More useful than N identical verifiers.
  • Judge panel — generate N approaches from different angles, score them in parallel, synthesize from the winner while grafting good ideas from the runners-up.
  • Loop until dry — for discovery of unknown size (bugs, edge cases), keep dispatching until K consecutive rounds turn up nothing new. A simple "stop at N" misses the tail.
  • Completeness critic — a final agent asking "what's missing: which modality wasn't tried, which claim wasn't verified, which source wasn't read?"

Related: Subagents · Tools overview