The inbox
Answer every decision your agents are waiting on from one ranked queue with venom inbox, set an attention budget, route items to code owners, and answer from your phone, a Matrix room or HTTP.
With several agents running, you are the scarce resource. venom inbox is one queue of what only you can decide, across every session on this machine, most urgent first.
Example
venom inbox # on a terminal: walk the queue, one key per answer
venom inbox list --json
venom inbox approve 3fa2 # an id or a unique prefix
venom inbox redirect 3fa2 "use the staging database, not production"Commands
| Command | What it does |
|---|---|
venom inbox |
On a terminal, walk the queue; otherwise list it. |
venom inbox list [--held] |
The open items; --held shows what the attention budget kept from you. |
venom inbox show <id> |
One item in full. |
venom inbox approve <id> |
Let the agent do it. |
venom inbox reject <id> [reason] |
Refuse; the agent is told your reason. |
venom inbox redirect <id> <instruction> |
Refuse and tell the agent what to do instead. |
venom inbox take-over <id> |
The agent stops and waits for your next message. |
venom inbox stats |
Minutes of your attention spent today, per agent, and what is left. |
venom inbox owners <path>... |
Who owns each path and which rule said so. |
--for <owner>[,<owner>] |
Only items owned by one of them, plus items nobody owns. |
--mine |
--for $VENOM_OWNER (your handle; comma-separated for several). |
--json |
One JSON object on stdout. |
What goes in
Item kinds are approval, question, merge and lease.
- Permission questions. Every question a TUI session asks is in its dialog and in the inbox at once; the first answer wins. You can answer from a second terminal without finding the session.
- Background results. A
venom dorun or a scheduled role posts a durablemergeitem with its summary, worktree and cost. - Stuck runs. A headless run that loops or keeps failing posts a
Stuck: …question with its last 8 calls (long tasks). - Paused runs. A run stopped by the session guard, or a scheduled run at its
max_usdormax_minutescap, postsPaused: …. Invenom serve, approving or replying continues the saved session with your message as its next prompt.
Apps on the harness post their own items with InboxStore.post (or InboxStore.submit, which goes through the attention budget) from @venom/harness/inbox.
Ranking
blast × uncertainty × (1 + minutes blocked). Blast radius (1 to 5) is how much harm a wrong yes does; uncertainty (1 to 5) is how little the agent knows. A cheap question that has waited an hour can outrank a risky one that just arrived. The inbox only collects your answer; it never decides anything.
Attention budget
Every item carries an estimated cost in minutes: an approval 1, a question or lease 1 to 2, a stuck trace 3, a merge review 2 plus 1 per 50 changed lines (at most 20). When you answer, the time from your first look to the answer (at most 15 minutes) is booked to the agent. Minutes count per local day.
inbox:
attention:
minutes_per_day: 60
threshold: 6| Key | Type | Default | What it does |
|---|---|---|---|
inbox.attention.minutes_per_day |
number | unset (no cap) | Minutes of your attention agents may spend in a day. |
inbox.attention.threshold |
number | 0 |
Lowest rank that reaches you. |
An agent's item is held when its rank is under threshold, or when it would overrun minutes_per_day and doesn't outrank the open item it would displace. Held items are kept for a week (venom inbox list --held), and the agent is told nobody was asked. Permission approvals and items marked safety are never held. A project's venom.yaml can set inbox only once the project is trusted.
Ownership
An item can name the paths it is about; the inbox looks them up in an ownership map in CODEOWNERS syntax and records owners. Files, strongest first: .venom/OWNERS, CODEOWNERS, .github/CODEOWNERS, docs/CODEOWNERS.
# .venom/OWNERS
/services/billing/ @acme/billing agent:billing-bot
/docs/ @docs-team
*.go @aliceWithin a file the last matching rule wins; across files the first file with a match wins. An owner is @user, @org/team, an email or agent:<name>. A rule with no owner un-owns its paths. venom inbox --mine then shows your items plus the ones nobody owns, so gaps in the map never hide an escalation.
Over venom serve
| Route | What it does |
|---|---|
GET /v1/inbox |
{items: [...]}, highest rank first |
GET /v1/inbox/{id} |
One open item; 404 inbox_item_not_found |
POST /v1/inbox/{id}/resolve |
{action, message?}; the waiting agent wakes. 400 for an unknown action or a redirect without message, 409 inbox_item_resolved |
On your phone
venom serve serves the inbox as a self-contained page at /v1/mobile with one-tap answers. It loads nothing from other origins, so it works on a LAN with the internet unplugged.
venom serve --host 0.0.0.0 --pair # listen on the LAN and print a pairing QR code
venom serve pair # a new code for a running serverThe code opens a one-time link valid for two minutes; the phone then stays paired for 12 hours or until the server restarts. The token never goes to the phone. Traffic is plain HTTP, so use --host only on a network you trust or put TLS in front. Set serve.public_url (or VENOM_SERVE_PUBLIC_URL) to the address your phone reaches, and Venom Cloud's Fleet page links to it.
In a Matrix room
venom serve can mirror the inbox into a Matrix room. Set VENOM_MATRIX_HOMESERVER, VENOM_MATRIX_TOKEN, VENOM_MATRIX_ROOM and VENOM_MATRIX_USERS (the Matrix ids allowed to answer; required). A listed user answers with approve <id>, reject <id> [why], redirect <id> <instruction> or take-over <id>. Use an unencrypted room.
Where it lives
One JSON file per item in ~/.venom/inbox/ ($VENOM_HOME/inbox), mode 0600. An open item whose process is gone is removed the next time anyone lists the queue, unless it is durable. Nothing leaves the machine.