Skip to content
Docs menu

Plugin roles

Install a standing agent a plugin ships (cron, prompt, mode, budget) as a reviewed schedule entry that venom serve runs.

View .md

A plugin can ship roles: standing agents such as a nightly flaky-test hunter or a changelog keeper. venom role add copies a role into schedules: in ~/.venom/config.yaml in full, so the config diff is the review and a later plugin update cannot change what an installed job does. venom serve runs the job like any schedule and files each run in the inbox.

Quick start

venom plugin add path:./role-flaky-test-hunter
venom role list                                    # built-in roles and plugins' roles
venom role show flaky-test-hunter
venom role add flaky-test-hunter --cwd ~/work/api
venom role remove flaky-test-hunter

Commands

Command What
venom role list [--json] roles from the built-ins and loaded plugins
venom role show <role> its schedule, mode, budget and prompt
venom role add <role> [--as <job>] [--cwd <dir>] [--cron <expr>] [--max-usd <n>] [--gear <name>] copy it into schedules:; the flags override the role's values
venom role remove <job> take that job out of schedules:

Shipping a role

A role is a JSON file in the plugin's roles/ directory (or the paths in the manifest's roles):

{
  "name": "flaky-test-hunter",
  "description": "Re-run the suite, list tests whose result changes, say the likely cause.",
  "cron": "0 4 * * 2,5",
  "mode": "plan",
  "max_usd": 0.75,
  "prompt": "You are the flaky-test-hunter. …",
  "gear": "eco"
}
Field Required What
name, description yes
cron yes when it runs
prompt yes the job's instructions
mode yes the permission mode; yolo is refused, so a shipped role cannot turn approvals off
max_usd yes the budget per run
gear, workspace no

Any other field is refused. A plugin that is not loaded (disabled, untrusted) offers no roles.