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.
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 servesJobs 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/apischedules:
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-huntervenom 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 invoicesThis 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. |