Plugin roles
Install a standing agent a plugin ships (cron, prompt, mode, budget) as a reviewed schedule entry that venom serve runs.
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-hunterCommands
| 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.