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 — 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>): 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).