Automation
Run venom without sitting at the keyboard, from scripted multi-agent pipelines and plan-then-execute runs to scheduled agents, background goals and pull request review bots.
Venom can work while you do something else. Each tool on this page starts unattended work at a different size, and they share three rules:
- Nobody is there to approve, so approvals are answered no. An unattended run uses its own permission mode (
plan,default,accept-editsorauto;yoloonly when you write it yourself,sudonever) plus anyallowrules you gave it. Every other approval question is refused at once, and the agent is told to report what it needed. - Every run has a spend cap. Caps are counted at list price over every model call the run makes, subagents included. A local model costs 0.
- Results wait for you in the inbox.
venom inboxis one queue for the decisions only you can make: permission questions, stuck runs, finished background work to merge.
Which tool to use
| You want to | Use | Cap (default) |
|---|---|---|
| Run the same multi-agent pipeline every time, written as code | Workflows (venom workflow run) |
--max-usd 2 |
| Let a big task be planned, approved, then carried out step by step with checks | Plan then execute (/plan-exec) |
none (per session) |
| Turn a design doc into a stack of small pull requests | Spec to pull requests (venom spec) |
--max-usd 10 |
| Split a cross-component change so two agents can work in parallel | Contract-first work | n/a |
| Run an agent on a cron or when something happens | Scheduled agents (venom schedule, venom serve) |
max_usd: 1 |
| Survive a crash, a reboot or a provider usage limit | Long tasks and resume (venom resume) |
n/a |
| Hand off one goal and get the result later | Background agents (venom do, venom intake) |
--budget 1 |
| Answer what agents are waiting on | The inbox (venom inbox) |
n/a |
| Review a diff, a pull request or every pull request | Code review and the review action | max-usd 0.50 in CI |
| Try a session's prompts on a cheaper model | Replay (venom replay) |
--max-usd required when paid |
| Work with teammates and other hosts | Teams of agents (venom fleet, venom handoff, venom board) |
n/a |
| Track spend per pull request, or delegate to subagents | Tasks and delegation | n/a |
Related
- The venom CLI quickstart covers permission modes and a first interactive session.
- Headless one-shot runs (
venom -p "…") and the--jsonoutput every subcommand takes are how scripts and CI drive these tools; Headless output in the CLI section documents both.
In this section
- 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.
- 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.
- The inbox: Answer every decision your agents are waiting on from one ranked queue with venom inbox, set an attention budget, route items to code owners, and answer from your phone, a Matrix room or HTTP.
- Plan then execute: Have the main model write a plan with a check per step, approve or edit it, then let cheap workers carry out each step while the main model verifies it with /plan-exec.
- Spec to pull requests: Turn a design doc or a GitHub issue into a stack of small, reviewed pull requests with venom spec, then keep the stack current as earlier slices merge.
- Contract-first work between agents: Split a change that spans two components into a contract slice and two parallel slices, so a producer and a consumer agent never wait on each other.
- Scheduled agents: Run background agents from venom serve on a cron or on events, each in a fresh git worktree with a spend and time cap, using built-in roles, plugin roles or recorded browser tasks.
- Long tasks and resume: Keep hours-long runs alive through crashes, reboots and provider usage limits with checkpoints and venom resume, and let the stuck detector shift gears or stop a run that loops.
- Code review: Review a diff, a GitHub pull request or a GitLab merge request read-only with venom review or /review, post the findings, watch a repository, and have the agent review itself before it opens a pull request.
- The review action: Review every pull request with venom review on a cheap gear from GitHub Actions or GitLab CI, with inline comments, one summary comment with the cost, and a spend cap.
- Replay a session on another model: Re-run a recorded session's prompts against another model, gear or route profile in a scratch workspace with venom replay, and compare turns, tokens, cost, tools and a check command.
- Teams of agents: See your and your teammates' agents with venom fleet, hand a session to a teammate or another host with venom handoff, coordinate subagents on the shared board, and drive agents from your issue tracker with venom board.
- Tasks and delegation: Count a session's spend toward a pull request, issue or tracker key with --task, /task and VENOM_TASK, and let the agent delegate work to subagents with the task tool.