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.
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 inboxThe 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.