# Approvals inbox

One place where people decide what agents asked to do, each decision tied to the exact change.

For: Approvers: the second person who must agree before an agent's change is applied.

Web page: https://candor.themethodic.com/screens/approvals-inbox

## Layouts

### List and detail

Pick it when: The default: approvers work through requests one after another.

Layout: A list of requests grouped by what they need from the viewer on the left, the selected request in full on the right.

Items:

- **Approval queue** (`approval-queue`, Pro; https://candor.themethodic.com/docs/approval-queue.md): Requests grouped by what they need from the viewer, soonest to expire first.
- **Approval request** (`approval-request`, Pro; https://candor.themethodic.com/docs/approval-request.md): What changes, where, what it touches, whether it can be undone, and a hash that ties the decision to that change.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): A person who can't decide sees why on the button, for example on their own request.
- **Change hash** (`change-hash`, Pro; https://candor.themethodic.com/docs/change-hash.md): The sha256 of a change, the same in the browser and on the server, so an approval can be checked where the change runs.
- **Change set review** (`change-set-review`, Pro; https://candor.themethodic.com/docs/change-set-review.md): A request that is many record edits, each kept or dropped; Apply sends only the kept ones, with their hash.

```bash
npx candor-ui add approval-queue approval-request locked change-hash change-set-review
```

### Board by what it needs

Pick it when: Several agents and many requests, where approvers triage by state: needs me, waiting on others, decided.

Layout: Three columns of request cards: needs you, waiting on someone else, decided.

Items:

- **Approval queue** (`approval-queue`, Pro; https://candor.themethodic.com/docs/approval-queue.md): The grouping, which a board renders as columns.
- **Approval request** (`approval-request`, Pro; https://candor.themethodic.com/docs/approval-request.md): Each card opens to the full request.
- **Agent activity** (`agent-activity`, Pro; https://candor.themethodic.com/docs/agent-activity.md): Who is working right now, so an approver knows what more is coming.

```bash
npx candor-ui add approval-queue approval-request agent-activity
```

### From an email or a phone

Pick it when: Approvers aren't in the app: the run pauses and the approval waits for them.

Layout: A compact approval page: the change, what it touches, and Approve and Deny at the bottom.

Items:

- **Approve from anywhere** (`approve-from-anywhere`, Premium; https://candor.themethodic.com/docs/approve-from-anywhere.md): The block: a run pauses at a write, the approver gets an id (not a link) and decides on a compact page.
- **Email layout** (`email-layout`, Pro; https://candor.themethodic.com/docs/email-layout.md): The email shell: one next step, and why you got it.
- **Approval request** (`approval-request`, Pro; https://candor.themethodic.com/docs/approval-request.md): The change they decide on.

```bash
npx candor-ui add approve-from-anywhere email-layout approval-request
```

## Rules that matter most here

- **Approve the exact change** (https://candor.themethodic.com/principles#approve-the-exact-change): A decision is tied to the change by a hash; if the change moves, the approval doesn't carry over.
- **A control that can't be used says why** (https://candor.themethodic.com/principles#locked-says-why): Your own request shows a locked button with the reason, not a hidden one.
- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): Neither Approve nor Deny is the default, and a reason field isn't pre-filled.

## Patterns that cover part of it

- Human-in-the-loop approval UI for AI agents: https://candor.themethodic.com/patterns/ai-approval-ui.md
- Durable approvals for long-running agents: https://candor.themethodic.com/patterns/durable-agent-approvals.md
- Apply only the record edits a person kept: https://candor.themethodic.com/patterns/apply-reviewed-change-set.md

A full-stack block builds this with an agent route and a store: `approvals-inbox` (https://candor.themethodic.com/docs/approvals-inbox.md). Each block has a `-claude` twin for the Claude Agent SDK.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build an approvals inbox with Candor UI: a place where people decide what agents asked to do.
Start from the approvals-inbox template (approvals-inbox-claude for the Claude Agent SDK) or compose ApprovalQueue and ApprovalRequest yourself.
ApprovalQueue groups requests by what they need from the viewer, soonest to expire first; ApprovalRequest shows what changes, where, what it touches and whether it can be undone.
Tie each decision to the exact change with its hash (changeHash, which gives the same hash in the browser and on the server): if the change is edited, the earlier approval no longer applies.
A person can't approve their own request; keep the button and wrap it in Locked so it says why.
Show a decision only after the server has recorded it, never an optimistic one.
Neither Approve nor Deny is pre-selected.
For approvers away from the app, use approve-from-anywhere: email an id, not a link, and decide on a compact page.
Read the ai-approval-ui and durable-agent-approvals patterns for the flow.

Start from the "List and detail" layout: A list of requests grouped by what they need from the viewer on the left, the selected request in full on the right.
Candor items: approval-queue (https://candor.themethodic.com/docs/approval-queue.md), approval-request (https://candor.themethodic.com/docs/approval-request.md), locked (https://candor.themethodic.com/docs/locked.md), change-hash (https://candor.themethodic.com/docs/change-hash.md), change-set-review (https://candor.themethodic.com/docs/change-set-review.md).
Install: npx candor-ui add approval-queue approval-request locked change-hash change-set-review
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```