---
title: Background agents
description: 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.
section: automation
order: 15
audience: [user, operator]
sources: [docs/do.md, cli/src/do.ts, cli/src/do-forecast.ts, cli/src/forecast.ts, cli/src/intake-command.ts, docs/integrations.md]
features: [automation.do, automation.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 {#do}

```bash
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](/docs/automation/schedules.md): 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](/docs/automation/inbox.md).

| 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 {#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 {#do-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](/docs/cli.md)).

## venom intake {#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.

```bash
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.

## Related

- [The inbox](/docs/automation/inbox.md)
- [Scheduled agents](/docs/automation/schedules.md)
