Omegacode

omegacode

Run a workflow file that orchestrates multiple agents deterministically. omegacode run <file.workflow.js> executes the file; it persists to ~/.omegacode/runs/<id>/ and prints a runId. Use omegacode serve (or run --open) to watch live progress. Each agent() call spawns a real Codex (gpt-5.x) or Claude Code agent — you pick the provider per call.

A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps). The file is where you encode that structure: what fans out, what verifies, what synthesizes.

When you write one, the right move is often hybrid: scout first (list the files, find the channels, scope the diff) to discover the work-list, then write a workflow to pipeline over it. You don't need to know the shape before the task — only before the orchestration step.

Common single-phase workflows you can chain across runs:

• Understand — parallel readers over relevant subsystems → structured map
• Design — judge panel of N independent approaches → scored synthesis
• Review — dimensions → find → adversarially verify (example below)
• Research — multi-modal sweep → deep-read → synthesize
• Migrate — discover sites → transform each (worktree isolation) → verify

For larger work, run several in sequence — read each result before deciding the next phase. You stay in the loop; each workflow is one well-scoped fan-out.

Every script must begin with export const meta = {...}:

export const meta = {
  name: 'find-flaky-tests',
  description: 'Find flaky tests and propose fixes',   // one-line summary
  phases: [                                            // one entry per phase() call
    { title: 'Scan', detail: 'grep test logs for retries' },
    { title: 'Fix', detail: 'one agent per flaky test' },
  ],
}
// script body starts here — use agent()/parallel()/pipeline()/phase()/log()
phase('Scan')
const flaky = await agent('grep CI logs for retry markers', { schema: FLAKY_SCHEMA })
// ...

The meta object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: name, description. Optional: phases. Use the SAME phase titles in meta.phases as in phase() calls — titles are matched exactly; a phase() call with no matching meta entry just gets its own progress group.

Script body hooks:

• agent(prompt: string, opts?: {provider?: 'codex' | 'claude-code' | 'opencode' | 'pi', model?: string, effort?: string, schema?: object, label?: string, sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access', cwd?: string, instructions?: string, maxTurns?: number, worktree?: boolean, key?: string}): Promise<any> — spawn an agent. Without schema, returns its final text as a string. With schema (a JSON Schema), the agent is forced to return JSON matching it and agent() returns the validated object — no parsing needed. Returns null if the user skips the agent mid-run (filter with .filter(Boolean)). opts.provider / opts.model: default to omitting both — the agent inherits the provider and model the workflow is being run with (set by --provider/--model, default codex), which is almost always correct. Only set them when the user explicitly asks for a specific provider/model, or you're highly confident a particular step needs a different one — and then set them together: provider and model are both-or-neither (a lone provider: or lone model: is an error, so a model meant for one provider can never silently ride a different provider's call). opts.label overrides the display label. opts.sandbox defaults to read-only; use workspace-write (write to cwd + network) only when the agent must write. opts.worktree: true runs the agent in a fresh git worktree — EXPENSIVE (setup + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is auto-removed if unchanged. opts.key is a stable resume pin that survives prompt-wording/reordering edits.
• pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives (prevResult, originalItem, index) — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to null and skips its remaining stages.
• parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to null in the result array — the call itself never rejects, so .filter(Boolean) before using the results. Use ONLY when you genuinely need all results together.
• log(message: string): void — emit a progress message to the user (shown as a narrator line above the progress tree)
• phase(title: string): void — start a new phase; subsequent agent() calls are grouped under this title in the progress display
• args: any — the value passed via --args '<json>' / --args-file <f>, verbatim (undefined if not provided). Use this to parameterize a workflow — e.g. pass a research question, target path, or config object.
• budget: {total: number|null, spent(): number, remaining(): number} — the run's output-token target, set with --budget N. budget.total is null if no target was set. budget.spent() returns output tokens spent this run. budget.remaining() returns max(0, total - spent()), or Infinity if no target. The target is a HARD ceiling, not advisory: once spent() reaches total, further agent() calls throw. Use for dynamic loops: while (budget.total && budget.remaining() > 50_000) { ... }, or static scaling: const FLEET = budget.total ? Math.floor(budget.total / 100_000) : 5.
• now(): number / random(): number — journal-seeded deterministic time/RNG. Use these instead of Date.now()/Math.random() (which throw — see below).

Agents are told their final text IS the return value (not a human-facing message), so they return raw data. For structured output, use the schema option — validation happens at the worker layer and the agent retries once on a mismatch.

Providers

Every agent() runs under a provider/model. By default, do NOT set provider or model per agent — each agent inherits the provider/model the workflow is being run with (--provider / --model, default codex), which is almost always what you want. Most workflows (including the canonical example and the patterns above) omit them entirely. Pin them only when the user explicitly asks for a specific provider/model, or you're confident a particular step needs a different one.

Provider and model are both-or-neither — at every site (per-call opts, meta.defaultProvider/defaultModel, --provider/--model): set both, or omit both to inherit the run defaults. A lone provider: (or lone model:) is rejected before the agent spawns. This exists because a lone provider override used to inherit the run-default model — a model belonging to a different provider. When you pin a provider, name the model explicitly (e.g. { provider: "codex", model: "gpt-5.5" }, { provider: "claude-code", model: "claude-fable-5" }). omegacode doctor shows which providers are installed/authed.

The four providers:

• codex (OpenAI, gpt-5.x) — the default. opts.effort tunes reasoning depth: "minimal" | "low" | "medium" | "high" | "xhigh". Requires the codex CLI authenticated (ChatGPT login); its built-in tools (incl. hosted image generation) come from that auth, and it ignores OPENAI_API_KEY. Native structured output via a free-form working turn then a schema-constrained extraction turn.
• claude-code (Anthropic) — via the Claude Agent SDK; requires the claude CLI / SDK available. opts.effort accepts "low" | "medium" | "high" | "xhigh" | "max" (max is Opus-tier; the model silently downgrades unsupported levels). Structured output is delivered on the final result only (intermediate messages stay free-form).
• opencode (OpenCode CLI ≥ 1.16.2) — spawn-per-call subprocess backend. model is an open provider/model string routed by opencode (e.g. "openrouter/anthropic/claude-sonnet-4.5"), required whenever provider: "opencode" is set (both-or-neither). Requires sandbox: "danger-full-access" — opencode has no enforceable confinement, so the default read-only sandbox is rejected with an actionable error. effort maps directly to OpenCode's provider-specific --variant flag. maxTurns is rejected. Structured output via a silent extraction turn that reuses the working session.
• pi (@earendil-works/pi-coding-agent ≥ 0.79.1) — spawn-per-call subprocess backend. model is an open pi model reference (e.g. "openrouter/moonshotai/kimi-k2.6"). Requires sandbox: "danger-full-access" — pi's tool allowlists are not OS confinement, so read-only/workspace-write are rejected. effort maps onto pi's full thinking range (none→off … max→xhigh); maxTurns is rejected. Structured output via a silent tool-less extraction turn.

(opts.effort is a single union — "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" — and each worker maps to its nearest supported level: minimal→low on claude, max→xhigh on codex/pi. opencode passes the value through as --variant.)

codex and claude-code honor every sandbox mode (read-only by default); opencode and pi are full-access-only — every call on them needs an explicit sandbox: "danger-full-access" (per call or via --sandbox), a deliberate fail-closed choice because neither CLI can honestly enforce confinement. All providers honor cwd; worktree: true isolates parallel file edits regardless of provider. Outdated opencode/pi binaries are refused at runtime (provider_outdated); omegacode doctor flags them up front.

The default case — omit provider, so fan-out and synthesis run on whatever provider the workflow was invoked with:

const findings = await parallel(AREAS.map(area => () =>
  agent(`Inspect ${area} and list concrete issues.`, { schema: FINDINGS_SCHEMA })))   // inherits the run's provider
const report = await agent(`Synthesize into a prioritized report:\n${JSON.stringify(findings.filter(Boolean), null, 2)}`)
return report

Pin a provider only when you mean to — e.g. a deliberate cross-provider verify pass (propose on the run's provider, refute on a different one) when the user has asked for that diversity:

const verified = await pipeline(
  suspects,
  s => agent(`Is this a real bug? ${s.desc}`, { schema: VERDICT }),                          // run's provider
  (v, s) => agent(`Try to REFUTE that ${s.desc} is a bug; default to refuted if unsure.`,
    { provider: "claude-code", model: "claude-fable-5", schema: VERDICT }).then(r => ({ ...s, real: v.real && !r.refuted })))

Scripts are plain JavaScript, NOT TypeScript — type annotations (: string[]), interfaces, and generics fail to parse. The script body runs in an async context — use await directly. Standard JS built-ins (JSON, Math, Array, etc.) are available — EXCEPT Date.now()/Math.random()/argless new Date(), which throw (they would break resume) and are rejected by a submit-time lint; use the injected now()/random() instead, or pass timestamps in via args. No filesystem, network, or relative import/require in the workflow body (the agents do the I/O).

DEFAULT TO pipeline(). Only reach for a barrier (parallel between stages) when you genuinely need ALL prior-stage results together.

A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1:

• Dedup/merge across the full result set before expensive downstream work
• Early-exit if the total count is zero ("0 bugs found → skip verification entirely")
• Stage N's prompt references "the other findings" for comparison

A barrier is NOT justified by:

• "I need to flatten/map/filter first" — do it inside a pipeline stage: pipeline(items, stageA, r => transform([r]).flat(), stageB)
• "The stages are conceptually separate" — that's what pipeline() models. Separate stages ≠ synchronized stages.
• "It's cleaner code" — barrier latency is real. If 5 finders run and the slowest takes 3× the fastest, a barrier wastes 2/3 of the fast finders' idle time.

Smell test: if you wrote

const a = await parallel(...)
const b = transform(a)        // flatten, map, filter — no cross-item dependency
const c = await parallel(b.map(...))

that middle transform doesn't need the barrier. Rewrite as a pipeline with the transform inside a stage. When in doubt: pipeline.

Concurrent agent() calls are capped at 100 per workflow by default (override with --concurrency N) — excess calls queue and run as slots free up. You can pass more items than the cap to parallel()/pipeline() and they all complete; only up to the cap run at any moment. Total agent count across a workflow's lifetime is capped at 1000 — a runaway-loop backstop set far above any real workflow. A single parallel()/pipeline() call accepts at most 4096 items; passing more is an explicit error, not a silent truncation.