Skip to content
Docs menu

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.

View .md

venom serve can run agents on a timer: a prompt, a repository and a cron expression. Each run is a headless session in a fresh git worktree, saved like any other session, with a one-line summary in the run log and a ScheduleDone hook event when it ends.

Example

venom schedule add deps --cron "0 3 * * 1-5" --cwd ~/work/api \
  --prompt "Update patch-level npm dependencies in package.json, run the tests, commit if they pass" \
  --mode auto --max-usd 0.50
venom schedule list
venom schedule run deps          # one run now, in this terminal
export VENOM_SERVER_TOKEN=$(openssl rand -hex 32)
venom serve --root ~/work        # runs the jobs on their schedule while it serves

Jobs only fire while venom serve runs, and a job's cwd must be inside one of its --root directories.

The command

Command What it does
venom schedule add <name> --cron <expr> --prompt <text> [options] Add or replace a job in ~/.venom/config.yaml.
venom schedule add <name> --role <role> [options] A job from a built-in role; its cron, prompt, mode and budget are the defaults.
venom schedule list [--json] Jobs with their next and last run.
venom schedule rm <name> Remove a job.
venom schedule run <name> Run a job now, here, and print how it ended.
add flag Default What it sets
--cwd <dir> the current directory where it runs
--gear <name> / --model <id> VENOM_MODEL the model (a gear also sets the thinking level)
--mode <mode> default plan, default, accept-edits, auto or yolo
--max-usd <n> 1 the run's spend cap at list price
--no-workspace worktree on run in cwd itself
--disabled enabled keep the job but never start it on schedule

Job names are lowercase letters, digits, ., _ and -, up to 64 characters.

In venom.yaml

venom schedule add writes ~/.venom/config.yaml; you can write jobs by hand in any config file. A project file's schedules: only count once the project is trusted (venom trust), so a cloned repository can't schedule work on your machine.

schedules:
  deps:
    cron: "0 3 * * 1-5"
    prompt: Update patch-level npm dependencies in package.json, run the tests, commit if they pass
    cwd: ~/work/api
    gear: cheap
    mode: auto
    max_usd: 0.5
    max_minutes: 60
    workspace: true
    enabled: true
    allow:
      - bash(npm test)
Key Type Default What it does
schedules.*.cron string required unless on Five fields in local time (minute hour day month weekday; *, ,, -, /, month and weekday names; 0 or 7 is Sunday) or @hourly, @daily, @weekly, @monthly. When day of month and day of week are both set, either matching is enough.
schedules.*.prompt string required What the agent is asked each run. Optional for a browser task.
schedules.*.on list none Events that also start a run (Events).
schedules.*.on.[].event string intent_closed, session_created, session_timeout or tool_call.
schedules.*.on.[].tool string or list any tool For tool_call: tool names, * globs, case-insensitive.
schedules.*.cwd path required (add: here) Absolute or ~/…, inside a venom serve --root.
schedules.*.workspace boolean true A new worktree sched-<name>-<time> from cwd's HEAD per run. Removed when the run changed nothing, kept with its branch when it did (venom workspace diff|merge|pr <name>). false runs in cwd.
schedules.*.gear string none A gear's model and thinking level.
schedules.*.model string VENOM_MODEL A model or alias.
schedules.*.mode string default The permission mode. Every approval question is answered no. yolo only when you write it; sudo is refused.
schedules.*.max_minutes number 120 A run still going is stopped (status budget) and leaves one Paused: inbox item; a reply resumes it. 0: no limit.
schedules.*.max_usd number 1 (0.25 for a browser task) The run is aborted once its model calls, subagents included, cost this much.
schedules.*.enabled boolean true false keeps the job but never starts it on schedule (run still works).
schedules.*.allow list none Permission rules the run may use without asking, such as browser(domain:example.com) or bash(npm test).
schedules.*.role string none A built-in role (Roles).
schedules.*.browser_task string none Replay a recorded browser task instead of a prompt (Browser tasks).
schedules.*.params map none The browser task's {{params}}; never a secret one.
schedules.*.browser string headless headless, launch, extension or attach.
schedules.*.attach_port number none For browser: attach: the Chrome remote-debugging port.

Roles

A role is a preset for a recurring chore. It supplies the prompt, a cron and the permission mode you leave out, and files each run's result in the inbox as a durable merge item with its cost and, when it changed files, the worktree to merge or drop. A role never merges anything.

venom schedule add bump --role dependency-bumper --cwd ~/work/api
schedules:
  bump:
    role: dependency-bumper
    cwd: ~/work/api
    cron: "0 3 * * 1-5"   # any key you write beats the role's
Role Default cron Mode max_usd What it does
dependency-bumper 0 3 * * 1 accept-edits 0.5 bumps patch and minor versions, runs the tests, commits if they pass
flaky-hunter 0 4 * * 2,5 default 0.75 runs the suite several times and reports tests whose result changes; edits nothing
dead-code 0 4 * * 3 plan 0.5 lists unused exports, files and dependencies with evidence
docs-drift 0 5 * * 4 plan 0.5 lists where docs name commands, flags or paths the code no longer has

venom schedule add stores only the role's name, so a later release can improve a role's prompt for jobs that haven't overridden it. The roles are SCHEDULE_ROLES in @venom/harness/schedules.

Plugin roles

A plugin can ship roles as JSON files in its roles/ directory (or the paths in venom.roles in its manifest). cron, prompt, mode and max_usd are required, gear and workspace optional; anything else, and mode: yolo, is refused.

venom role list
venom role show flaky-test-hunter
venom role add flaky-test-hunter --cwd ~/work/api   # [--as <job>] [--cron …] [--max-usd …] [--gear …]
venom role remove flaky-test-hunter

venom role add copies the role into schedules: in full, so the config diff is the review and a later plugin update can't change what an existing job does.

Browser tasks

A recorded browser task can run on a schedule, for example "every weekday at 8:00, download the new invoice". The replay needs no model, so a run that goes as recorded costs nothing.

venom browser task schedule invoices --cron "0 8 * * 1-5" --param month=october
venom browser task schedules
venom browser task unschedule invoices

This writes a job with browser_task, params and allow rules for the sites the script opens. A run replays the script in its own browser and saves what it produced in ~/.venom/schedules/outputs/<job>/<time>-<run>/ (each extract step as <name>.txt, downloads in downloads/, the outcome in result.json). If a step fails because the page changed, a session takes over with the browser tools, capped at max_usd, finishes the run and saves the fix to the script. Steps that need a person (an anti-bot check, a password field, a refused permission) fail the run without calling the model. Secret parameters come from VENOM_PARAM_<NAME> in venom serve's environment and are never shown to the model.

Events

With an on: block a job also starts on something that happened. With no cron it runs only on its events.

schedules:
  shell-audit:
    on:
      - event: tool_call
        tool: [bash, write]
    prompt: Review the commands the session just ran in ~/work/api and flag anything that touches config/production.yaml
    cwd: ~/work/api
    max_usd: 0.25
Event Fires when
intent_closed an intent in the ledger is closed (not abandoned), seen on the 30-second check
session_created a client opens a session on this server
session_timeout the server closes an idle session
tool_call a session's agent starts a tool call; tool: filters by name

Sessions that a scheduled run opens are not events, so a job can't start itself. Each event type keeps a watermark in ~/.venom/schedules/state.json, set past everything that already happened the first time, so adding on: never runs for the past and a restart never fires an event twice. A job runs one at a time: events that arrive meanwhile wait in a queue of at most 100.

Vague goals

Nobody is there to ask what a job meant, so its prompt is checked before it can spend. It must be at least 40 characters and name a concrete target: a file path, a `symbol`, Foo.bar or fooBar(), a test name, a URL, or an issue such as #123 or VEN-12. A prompt that fails is refused by venom schedule add, reported as a problem when venom serve loads it, and never run. [open-ended] anywhere in the prompt always passes, for chores with no single target. Interactive prompts are never checked.

Missed runs and results

When the server starts, and every 30 seconds after, a job whose time has passed runs once (trigger: catch-up), so a laptop asleep for three days runs an hourly job one time. A job seen for the first time never runs for the past, and a job still running when its time comes again is skipped.

Each run is a saved session (venom -r, venom export). The run log ~/.venom/schedules/runs.jsonl holds the status (completed, error, aborted, budget), trigger (cron, catch-up, manual, event), cost, duration, a one-line summary, the session id and the worktree.

Notify yourself with a ScheduleDone hook; its matcher is tested against the job name:

hooks:
  - event: ScheduleDone
    matcher: deps
    command: 'jq -r ".schedule + \": \" + .summary" | terminal-notifier -title venom'

Daily digest

venom digest prints what landed in the last day (first-parent commits on HEAD), what waits in the inbox and what scheduled runs cost. No model runs.

venom digest                 # the last 24 hours
venom digest --since 3d --json
venom digest add --cron "0 8 * * *" --cwd ~/work/api
Flag Default What it does
--since <Nh|Nd> 24h the window
--json off the facts as JSON
add --cron <expr> 0 8 * * * saves a job named digest
add --cwd <dir> here the repository the job reads
add --gear <name> cheap the gear that words it

The digest job runs in plan mode with max_usd: 0.05 and no worktree. Its prompt holds {{digest}}, which any schedule prompt may use: the server fills in the facts at run time, so the model only words five lines. Deliver it with a ScheduleDone hook with matcher: digest.

Over HTTP

venom serve adds GET /v1/schedules (jobs with nextRunAt, lastRun and queued), POST /v1/schedules/{name}/run (202 with the run as it started; 409 schedule_running), GET /v1/schedules/runs?schedule=&limit= and GET /v1/schedules/runs/{runId}/output?file= for a browser task's files. The harness server API reference (/docs/api/harness-server) has the schemas. The Python client has schedules(), run_schedule(), schedule_runs() and schedule_run_output(). A run's session counts against --max-sessions while it runs.

Scheduled runs make no network calls of their own beyond the model endpoint you configured.

Troubleshooting

Symptom Cause
A job never runs venom serve isn't running, cwd isn't under a --root, the job is enabled: false, or the project file isn't trusted.
Refused at add with "what to add" The prompt failed the vague-goal check. Name a file or target, or add [open-ended].
The run ends early and says it needed approval Every approval is answered no. Add an allow rule or a stronger mode.
Status budget It hit max_usd or max_minutes. Answer the Paused: inbox item to continue.