---
title: Scheduled agents
description: 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.
section: automation
order: 50
audience: [user, operator, builder]
sources: [docs/schedules.md, cli/src/schedule.ts, packages/harness/src/schedules/index.ts, packages/harness/src/schedules/events.ts, docs/venom-config.schema.json]
features: [automation.schedule, automation.digest]
---

`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 {#example}

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

| 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 {#config}

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

```yaml
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](#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](#roles)). |
| `schedules.*.browser_task` | string | none | Replay a recorded browser task instead of a prompt ([Browser tasks](#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 {#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.

```bash
venom schedule add bump --role dependency-bumper --cwd ~/work/api
```

```yaml
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 {#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.

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

```bash
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 {#events}

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

```yaml
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 {#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 {#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:

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

## Daily digest {#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.

```bash
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 {#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 {#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](#vague-goals). 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. |

## Related

- [Long tasks and resume](/docs/automation/long-tasks.md)
- [Workflows](/docs/automation/workflows.md)
