---
title: Plugin roles
description: Install a standing agent a plugin ships (cron, prompt, mode, budget) as a reviewed schedule entry that venom serve runs.
section: plugins
order: 110
audience: [user, operator, builder]
sources: [cli/src/role-command.ts, docs/schedules.md, packages/harness/src/plugins, examples/plugins]
features: [plugins.role]
---

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

```bash
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`):

```json
{
  "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.

## Related

- [Write a plugin](/docs/plugins/writing.md)
- [Install and manage plugins](/docs/plugins/installing.md)
