Skip to content
Docs menu

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.

View .md

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 do run or a scheduled role posts a durable merge item 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_usd or max_minutes cap, posts Paused: …. In venom 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                  @alice

Within 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 server

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