---
title: Workflows
description: Script a multi-agent pipeline in JavaScript, check it in next to the code, and run it with venom workflow run or /workflow with a spend cap, resume and per-agent worktrees.
section: automation
order: 10
audience: [user, builder, agent]
sources: [docs/workflows.md, cli/src/workflow.ts, packages/harness/src/extensions/workflows.ts, examples/workflows/review-verify.mjs]
features: [automation.workflow]
---

A workflow is a multi-agent pipeline written as a JavaScript file in `.venom/workflows/`. The script decides the order, what runs in parallel and how one result feeds the next, so the same input runs the same agents every time. The model only does the work inside each `agent()` call.

## A first workflow {#example}

Save this as `.venom/workflows/add-tests.mjs`:

```js
export default async ({ agent, pipeline, phase }) => {
  phase("plan");
  const { files } = await agent("List the source files that lack tests", {
    agent: "explorer",
    schema: {
      type: "object",
      required: ["files"],
      properties: { files: { type: "array", items: { type: "string" } } },
    },
  });
  phase(`write tests for ${files.length} files`);
  return pipeline(
    files,
    (f) => agent(`Write unit tests for ${f}`, { label: `test ${f}` }),
    (report, f) => agent(`Run the tests for ${f} and fix what fails`, { label: `fix ${f}` }),
  );
};
```

Run it:

```bash
venom workflow list
venom workflow run add-tests --max-usd 1
```

In the TUI, `/workflow` lists the scripts and `/workflow run add-tests` runs one, with progress in a panel above the editor.

## The script API {#api}

`.venom/workflows/<name>.mjs` (or `.js` in an ESM package) exports a default async function. It receives one object:

| Name | What it does |
|---|---|
| `agent(prompt, opts?)` | Runs one subagent and resolves with its report. See the options below. |
| `parallel([...])` | Runs thunks (`() => agent(...)`) or promises together, waits for all, then throws the first error if there was one. |
| `pipeline(items, ...stages)` | Sends each item through the stages in order (`stage(value, item, index)`). Different items move through at the same time. |
| `phase(title)` | Prints a heading in the progress. |
| `log(text)` | Prints a line in the progress. |
| `args` | The command's other flags: `--base main` gives `args.base === "main"`, `--dry` gives `true`, positionals are in `args._`. |
| `cwd`, `runId` | Where it runs, and this run's id. |

The return value is printed when the run ends: a string as it is, anything else as JSON.

### `agent()` options {#agent-options}

| Option | Default | What it does |
|---|---|---|
| `schema` | none | A JSON Schema. The agent must reply with JSON only and `agent()` resolves with the parsed value. A reply that doesn't match fails the call. |
| `label` | the prompt | The name in the progress lines. |
| `model` | the agent's | A tier (`fast`, `smart`, `main`) or a model id. |
| `agent` | `worker` | The subagent definition: `worker`, `reviewer`, `verifier`, `explorer`, or one of your own `.claude/agents/*.md`. |
| `isolation` | see below | `"worktree"`: its own temporary git checkout at worker scope. `"none"`: the run's checkout. |

## Running a workflow {#run}

```bash
venom workflow run <name> [options] [script args]
```

| Flag | Default | What it does |
|---|---|---|
| `--max-usd <n>` | `2` | Stops the run once its agents cost this much at list price. Running agents are stopped, no new one starts, and the run ends with status `budget`. |
| `--concurrency <n>` | `4` | Agents at once. The rest wait, first come first served. |
| `--resume <runId>` | none | Runs the script again; agents that already finished return their saved result at no cost. |
| `--model <id>` | the session's | The session's model; agents on the main tier use it. |
| `--isolation <w>` | `worktree` in a git repo | `worktree` gives every `agent()` call that doesn't say otherwise its own checkout; `none` runs them in this checkout. |
| `--mode <mode>` | `accept-edits` | The session's permission mode: `plan`, `default`, `accept-edits` or `auto`. |
| any other `--flag` | | Passed to the script as `args.<flag>`; positionals as `args._`. |

`venom workflow run` writes progress to stderr and the result to stdout. With `--json` it prints `{ok, name, status, result}` (or `{ok, workflows:[{name, file}]}` for `list`); error codes are `usage`, `workflow_not_found` and `workflow_failed`.

### How agents run {#how}

- Each `agent()` call is a subagent of the session, the same child session the `task` tool starts. Its permission mode is the agent's own, capped at the session's.
- `venom workflow run` is headless: nobody can approve anything, so every approval question is answered no.
- **Isolation.** An agent with `isolation: "worktree"` works in its own temporary git worktree at worker scope: it cannot read `~/.venom` or another checkout's `.env`, has no credential-shaped environment variables, reaches only package registries, and may change only its own branch. Its changes come back as a note under its report. The CLI defaults to `worktree` because nobody is watching; interactive `/workflow run` keeps agents in the session's checkout unless you pass `--isolation worktree`. Outside a git repository agents run in the directory and the run says so.
- **Trust.** A workflow is code from the repository. It runs only when the project is trusted (`venom trust`) and only when you start it. The model has no tool to start one.

### Resume {#resume}

Every agent that finishes is written to `~/.venom/workflows/runs/<runId>.jsonl`. The end line prints the run id; pass it to `--resume`. An agent is matched by its prompt, schema, model, agent, label and isolation, plus how many times the script asked for exactly that before. Keep scripts deterministic (no `Math.random()`, no clock in prompts) or a resumed run won't match its cache. A reply that failed its schema isn't saved, so it runs again. Neither is a partial reply: an agent that stopped at its turn limit or its time or cost budget, or whose final reply was still cut off at the output-token limit. The script still gets that text from `agent()`, and its progress line ends with `partial (<reason>)`.

## Progress {#progress}

The run prints one line per step: the run id, each `phase`, each agent starting (`▸`) and finishing (`✓` with its time and cost, or `cached`; `~` with `partial (<reason>)`; `✗` with the error), and an end line with the status, the total cost and how many agents were partial. The TUI shows the latest twelve. `venom serve` clients get each line as a `workflow` harness event (`kind`, `line`, and `status` on `end`) when a prompt runs `/workflow run …`; ACP editors get them as message text.

Workflows add no tool and no system-prompt text, so a session that never runs one pays nothing for them.

## Troubleshooting {#troubleshooting}

| Symptom | Cause |
|---|---|
| `workflow_not_found` | No `.venom/workflows/<name>.mjs` or `.js` in this project. Check `venom workflow list`. |
| The run refuses to start | The project is not trusted. Run `venom trust`. |
| An agent fails with a schema error | Its reply was not JSON matching `schema`. Tighten the prompt or loosen the schema; the failed call is not cached. |
| Ends as `budget` | `--max-usd` was reached. Resume with `--resume <runId> --max-usd <higher>`. |
| A resumed run re-runs everything | The prompts changed between runs (a timestamp or random value in a prompt). |

## Related

- [Plan then execute](/docs/automation/plan-execute.md) runs steps one after another with a verifier; a workflow runs them in the shape you script.
- [Scheduled agents](/docs/automation/schedules.md) can run a prompt on a cron.
