Skip to content
Docs menu

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.

View .md

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-edits or auto; yolo only when you write it yourself, sudo never) plus any allow rules 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 inbox is 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
  • The venom CLI quickstart covers permission modes and a first interactive session.
  • Headless one-shot runs (venom -p "…") and the --json output 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.