# Agentflow — script-driven multi-agent orchestration You orchestrate turn-by-turn by default: every subagent result lands in your context window. Agentflow moves the loop, branching, and intermediate results into a JavaScript file that a runner executes — you keep only the final answer. ## When to use - Fan-out beyond ~4 independent agent calls (file-per-file reviews, repo-wide audits, per-endpoint checks, N-variant drafting). - Staged pipelines where later phases consume earlier results. - Runs you may need to interrupt and resume. - Results are bulky: the script holds them; you read the synthesis. ## When NOT to use - 1-4 subagent calls — just use your harness's native subagent tool; a CLI session per call has real startup cost, so keep fan-out granularity meaningful (a whole file audit, not a function rename). - Anything needing shared state, locks, or transactions between agents — workflow agents share nothing but the filesystem. - Claude Code's **native** Workflow tool (ultracode/`/deep-research`) — inside Claude sessions, prefer it; it is faster and cheaper than spawning `claude -p`. ## How it works ```bash agentflow run workflow.mjs --harness devin --concurrency 8 agentflow run workflow.mjs --resume # after interrupt agentflow doctor # check harness availability ``` Each `agent()` call spawns one **non-interactive CLI session** of the selected harness as a subprocess, in a fresh context, and resolves to `{text, json}` or `null` on failure. Calls queue under a bounded concurrency pool (default 8). Every settled call is journaled to `.agentflow/runs/.jsonl`; `--resume` replays settled results and re-runs only what never finished. ## Workflow script contract `.mjs` file, top-level `await` allowed, globals injected: | Global | Signature | Notes | |---|---|---| | `agent` | `(prompt, opts?) => Promise<{text, json, usage?} \| null>` | opts: `label`, `model`, `schema`, `worktree`, `cwd`, `timeout` (ms), `permission`, `retries`. `usage` is `{promptTokens, completionTokens, cachedTokens, steps}` when the harness reports it — **devin only** today (from `--export` final_metrics); also journaled and summed by `status`/`watch` | | `parallel` | `(thunks) => Promise` | `parallel(files.map(f => () => agent(...)))` — order preserved, `null` per failure | | `pipeline` | `(items, ...stages) => Promise` | each item flows through stages; `null` short-circuits that item | | `batch` | `(items, opts?) => Promise` | async fan-out on **openrouter** (one OR Batch job per N prompts, ~40–60% off, ≤24h window), **devin** (N cloud sessions — `devin_mode` model, `structured_output` collected; swe-2 models are free), **perplexity** (N `/v1/async/sonar` requests — async accepts **`sonar-deep-research` only**), **openai** (Batches API, ~50% off, 24h) or **anthropic** (Message Batches, ~50% off, 24h). Items: `{prompt, label?, model?, schema?, maxTokens?}`; all share ONE model (`opts.model` or per-item). opts: `batchPollMs` (15s), `batchTimeoutMs` (2h). Results align to input order; each item consumes a normal call index | | `phase` | `(name) => void` | labels stderr progress | | `log` | `(msg) => void` | stderr; keep secrets out | | `args` | array | args after `--` on the CLI | | `meta` | object | from `export const meta = {...}` | Constraints: - `export const meta = { name, description, phases }` is the only export; it must be a **plain object literal**. `phases` is an array of phase-name strings matching your `phase()` calls (parity with Claude's native contract). - No static `import`/`export` — scripts are self-contained. Dynamic `await import('node:fs')` works. - Determinism is your job: resume replays by call order, so keep `agent()` call order stable across runs (don't drive call order off `Date.now()` or unordered directory listings). ## Per-harness adapter table | `--harness` | Spawns | `model` | `schema` | `worktree` | `permission: 'escalated'` | |---|---|---|---|---|---| | `devin` (default) | `devin -p` | `--model` (e.g. `claude-haiku-5-5-low`, `adaptive`) | prompt-level JSON instruction | planned | `dangerous` | | `claude` | `claude -p --output-format json` | `--model` | prompt-level | no | `bypassPermissions` | | `codex` | `codex exec` | `-m` | native `--output-schema` | `--worktree` | `--dangerously-bypass-approvals-and-sandbox` | | `opencode` | `opencode run --format json` | `-m provider/model` | prompt-level | no | `--auto` | | `ori` | `ori code -p` | `--model ` — any model on OpenRouter | prompt-level | no | `self-drive` (binary approval surface; `manual` stalls headless) | | `openrouter` | in-process `POST /chat/completions` — **no subprocess, no tools** | OR slug (default `z-ai/glm-5.3-flash`) | prompt-level | n/a | n/a — needs `OPENROUTER_API_KEY` in env | | `perplexity` | in-process `POST /chat/completions` — grounded answers + `citations` | `sonar` (default), `sonar-pro`; **batch: `sonar-deep-research` only** | prompt-level | n/a | n/a — needs `PERPLEXITY_API_KEY` in env | | `openai` | in-process `POST /v1/chat/completions` — **no subprocess, no tools** | OpenAI slug (default `gpt-4.1-mini`) | prompt-level | n/a | n/a — needs `OPENAI_API_KEY` in env | | `anthropic` | in-process `POST /v1/messages` — **no subprocess, no tools** | Anthropic slug (default `claude-haiku-4-5`) | prompt-level | n/a | n/a — needs `ANTHROPIC_API_KEY` in env | | `echo` | none (test adapter) | — | canned | — | — | `openrouter` is the cheapest surface — use it for tool-free stages (decompose, classify, verify prose, synthesize); harness adapters only where agents need the filesystem. For latency-tolerant volume, `batch(items)` runs the harness's async-jobs surface instead of N sync calls — the run polls until done (interrupt mid-poll is safe: `--resume` re-polls the same journaled ids, never resubmits). On openrouter that's one `/batches` job (model must be batch-capable); on devin it's one Cloud session per item (`structured_output` is the result channel, sessions idle at `waiting_for_user` once produced — that is the completion signal); on perplexity it's one async sonar request per item (`COMPLETED` + `response` — grounded answers carry `citations` through to the result); on openai it's a JSONL file upload + one `/v1/batches` job; on anthropic one `/v1/messages/batches` call (`max_tokens` required — default 8192, per-item `maxTokens` overrides). **`--via ori`** wraps workers in Ori's OpenRouter environment (`ori claude -p ...`) — the harness keeps its own flags and parsing, but credentials and `model:` values route through OpenRouter (`model: 'x-ai/grok-4-fast'`, `deepseek/...`, etc.). Ori consumes `--model` and `--reasoning-effort` itself in wrapper mode — `agent(..., { reasoningEffort: 'high' })` translates to the harness's native mechanism. Wrappable harnesses: claude, codex, opencode, grok, kilo, hermes, cline, pi, muse, omp, prime-agent — no devin launcher exists. Requires `ori` on PATH; `--via` on the CLI or `via: 'ori'` in `agentflow.json` applies to every `agent()` call; a call can opt out with `via: 'direct'`. **`worktree: 'auto'`** gives the call its own git checkout — the runner runs `git worktree add --detach` under `.agentflow/worktrees/` and sets that call's `cwd` there (journaled as a `worktree` record). Use it when file-mutating agents would collide in one checkout. `'auto'` is runner-owned and consumed before the adapter sees the spec; `worktree: true` still passes through to adapter-native flags (codex `--worktree`). Worktrees deliberately persist after the run — `agentflow clean` reclaims them for ended runs (`--all` also sweeps unrecorded dirs under `.agentflow/worktrees/`). Default permission postures are least-privilege (`smart` devin / `auto` claude / `workspace-write` codex / none opencode). Headless agents that hit an approval prompt fail with `permissionDenied` journaled — prefer widening the prompt or `permission: 'escalated'` over re-running blindly. ## Cost discipline Every harness `agent()` is a full session — real tokens plus seconds of startup; `openrouter` adapter calls are a single completion (~$0.01–0.05). Measured numbers and per-model tables: `docs/research/orchestration-economics.md`. Prefer cheap models for extraction/verification volume (`z-ai/glm-5.3-flash`, `openai/gpt-6-luna`, `deepseek/deepseek-v4.1-flash`, `claude-haiku-5-5-low` on devin which is ~$0.10/$0.50, free `swe-2-*`) and reserve strong models for the synthesis call. Worker tier × N dominates — orchestrator price barely matters. `--cache` memoizes identical calls content-keyed across reruns; `batch()` on openrouter cuts ~40–60% for latency-tolerant stages (one job, ≤24h window — poll defaults are `batchPollMs`/`batchTimeoutMs` per call or in `agentflow.json`). The research says: fan out on parallelizable sub-questions, always end in centralized synthesis/verification (independent agents amplify errors ~17×), and don't fan out sequential work. **Guards:** `--strict` rejects scripts using `Date.now`, `Math.random`, `new Date`, or `crypto.randomUUID` in the body (line-numbered errors, before any agent spawns) — nondeterminism silently misaligns `--resume`'s positional replay. `--max-agents ` (default 1000) caps total `agent()` calls per run. `--retries ` (default 0) re-runs transient failures — cheap models flake on empty completions under burst; `agent(p, {retries: 2})` for volume stages. Never retried: `permissionDenied` and `timedOut`. All three settable in `agentflow.json` (`"strict": true`, `"maxAgents": 200`, `"retries": 1`). **Backgrounded runs:** `--detach` returns immediately with a run-id (the child keeps running, output in `.agentflow/runs/.log`). `agentflow status ` prints settled/total + outcome (exit 2 while running), `agentflow tail ` streams journal events until run-end, and `agentflow watch [id]` renders a live per-lane terminal view (in-flight spinners, batch poll progress, per-call tokens; falls back to `tail` output when piped). Use detach for long fan-outs and check back — same model as Claude's detached Workflow. ## Autonomous operation A launched run needs no babysitting — the runner owns the pool, retries, SIGINT drain, and journaling. Your job is the loop around it: 1. **Launch** with `--detach` for anything longer than a few calls; keep the run-id it prints. 2. **Monitor** with `watch ` (TTY) or `status ` (scripts) — token totals accumulate per call on devin so spend is visible mid-run. 3. **Heal**: interrupted or partially failed runs resume exactly — `agentflow run w.mjs --resume --harness ` replays settled work and re-runs only the gaps; mid-poll batch interrupts re-poll the journaled batch id, never resubmit. A `null` slot in results is a failed call — count it, retry the script with `--resume` if it matters, don't panic-rerun everything. 4. **Report** the synthesis + `run ` (journal keeps prompt/result text; `status`/`watch` keep totals). Don't re-orchestrate per-call in your own context — that's the thing agentflow exists to remove. If a stage needs a decision from you, gate it between two `run` invocations, not inside the workflow. `agentflow stop ` SIGTERMs the journaled pid only when it verifies as the run's own process (agentflow cmdline + start time matching the journal — a reused or unverifiable pid is never signaled), then waits for run-end up to `grace + 15s`; a still-draining run stays resumable and `status` keeps reporting it. Exit codes for `status`/`tail`: `0` ended ok, `1` ended error/determinism-lint, `130` interrupted, `2` running / orphaned / no-journal (stdout says which). A run whose pid is dead but journal has no run-end reports **orphaned** — resume it with `agentflow run