Workflows
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.
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
Save this as .venom/workflows/add-tests.mjs:
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:
venom workflow list
venom workflow run add-tests --max-usd 1In the TUI, /workflow lists the scripts and /workflow run add-tests runs one, with progress in a panel above the editor.
The script 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
| 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
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
- Each
agent()call is a subagent of the session, the same child session thetasktool starts. Its permission mode is the agent's own, capped at the session's. venom workflow runis 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~/.venomor 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 toworktreebecause nobody is watching; interactive/workflow runkeeps 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
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
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
| 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 runs steps one after another with a verifier; a workflow runs them in the shape you script.
- Scheduled agents can run a prompt on a cron.