---
title: The inbox
description: 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.
section: automation
order: 18
audience: [user, operator, builder]
sources: [docs/inbox.md, cli/src/inbox.ts, packages/harness/src/inbox, docs/venom-config.schema.json]
features: [automation.inbox]
---

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 {#example}

```bash
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 {#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 {#items}

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`](/docs/automation/background.md) 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](/docs/automation/long-tasks.md#stuck)).
- **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 {#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 {#attention}

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.

```yaml
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 {#owners}

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

```text
# .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 {#http}

| 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 {#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.

```bash
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 {#matrix}

`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 {#files}

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.

## Related

- [Background agents](/docs/automation/background.md)
- [Long tasks and resume](/docs/automation/long-tasks.md)
