Skip to content
Docs menu

Background agents

Hand a goal to a background agent in its own worktree with venom do, see a cost forecast first, and let a machine work through the Linear and Jira issues your org assigns with venom intake.

View .md

Two ways to give venom work and walk away: venom do for a goal you type, and venom intake for issues your organisation hands to venom in Linear or Jira.

venom do

venom do "fix the flaky test in cli/test/hud.test.ts" --risk low --budget $2 --by 17:00
venom do list
venom inbox

The command writes a spec to ~/.venom/do/<id>.json, starts a detached run and returns at once. The run is a one-shot scheduled job: a new git worktree, the job's model, a spend cap, and every approval question answered no. When it ends, or at --by, one item lands in the inbox.

Flag Default What it does
--risk <tier> low What it may do unattended. low (default mode): every approval is answered no. medium (accept-edits): edits files freely. high (auto): a classifier on venom-fast allows safe commands, in its worktree.
--budget <usd> 1 Stop at this spend at list price (2 or $2).
--by <time> none Give up at HH:MM (today, or tomorrow if it has passed), or 30m / 2h from now.
--model <id> VENOM_MODEL The model or alias.
--gear <name> none A gear's model and thinking level.
--cwd <dir> here The repository.
--json off Print the run as JSON.
--forecast off Print tokens and dollars per gear (p50 / p90) from similar past sessions and start nothing. Same as venom forecast "<goal>".

venom do list shows the runs; each one's log is ~/.venom/do/<id>.log.

The forecast

Once three runs have finished, venom do prints what the new one will likely cost before it starts, for example forecast ~$0.25 ($0.20-$0.30, from 5 similar past runs). It is the median of the five most similar finished runs (goal words weigh most; the same risk, model and gear count too), with their quartiles as the range. A forecast above --budget says the run will likely stop at the cap. With fewer than three runs and a --gear or --model, the forecast comes from your saved sessions instead. It reads local files and your orchestrator's routing report only and is advisory: the budget stays the limit.

The result

The inbox item has kind merge, is titled with the run's status, goal and cost, and holds the agent's summary, the worktree path and the evidence bundle of what changed, with the changed files as its paths so it reaches their owners. It is durable: it waits until you answer it with venom inbox approve <id> or venom inbox reject <id>. Merge or drop the worktree with venom workspace merge or venom workspace rm. A run past --by is stopped and reported with whatever its worktree holds.

To run several attempts at the same goal and keep the best, use venom try "<goal>" -n 3 --check "<cmd>" (documented in the CLI section).

venom intake

venom intake run turns this machine into a runner for the Linear and Jira issues your organisation hands to venom (set up under Integrations in Venom Cloud). It works one issue at a time: claims a job, runs venom headless on the issue in its own worktree on a branch venom/<key>-<slug>, pushes the branch, opens the pull request with gh and reports back. The cloud then comments on the issue and moves its status.

venom cloud login
venom intake run --repos ~/src --max-usd 5 --risk medium
Flag Default What it does
--name <runner> this host's name The runner's name in the console.
--repos <dir> here Where your clones live: acme/api is <dir>/acme/api or <dir>/api.
--max-usd <usd> 5 The most one job may spend here. A job with a higher cap waits for another runner.
--risk <tier> medium low answers every approval no, medium edits files, high also runs commands (tests, builds) in its worktree.
--draft off Open draft pull requests.
--once off Work on at most one job, then exit.

Credentials come from venom cloud login or VENOM_CLOUD_URL and VENOM_CLOUD_KEY; nothing is contacted without them, and the runner listens on no port. Each job's inference goes to the cloud with a key the cloud minted for that job, capped at the job's budget and revoked at the end, never the runner's own key. A stop answer from the cloud (cancelled, capped, lost) aborts the agent. git and gh run with your own credentials.