The inbox lists every open gate assigned to you across all factories, most urgent first, so you can approve, reject or answer in one place.
What appears in the inbox
Each item is an open gate:
| Kind | Example title | You can |
|---|---|---|
| Spec | Approve the spec for "Team invites" | Approve or reject with feedback |
| Preview | Accept the preview of "Team invites" | Approve or reject with feedback. Only when a preview provider (Vercel) is configured. |
| Question | verify keeps failing on "Fix the nav" | Answer, approve to resume, or reject to cancel |
| Review | Review "Team invites" | Read the diff, comment on lines, approve, request changes or merge, as your GitHub account |
| Custom | Legal sign-off | Approve or reject |
Each item shows its work item (title, state, factory, pull request, preview URL and spec), the question or details, and evidence links such as the spec pull request, the preview and the videos.
You see gates assigned to you, plus gates with no assignee. Assignees come from the gate's approvers; see Pipelines and gates.
Reviewing a pull request
A Review item opens the diff in the side pane, file by file. Hover a line and click the comment button to leave a line comment; your comments go out together when you submit:
- Approve posts an approving review.
- Request changes posts the review and sends your summary and line comments to the agents, which revise the pull request.
- Comment only posts the line comments without a verdict.
- Merge merges the pull request; the task completes.
Kiln acts as your own GitHub account, never as the Kiln app (agents never approve or merge; see ADR-010). Link GitHub once from the pane or your linked accounts. If you merged elsewhere, Confirm it landed closes the task. On the run page, Request changes on the merge gate (or a follow-up message) sends your note to the agents without a GitHub review.
The review page
A task with a pull request also has a page of its own at /review/<task id>; the run page links to it with Review. It answers "what happened, and can I approve it" before you read any chat:
- What was wrong: the triage summary.
- Proof: one before/after image pair (or one image) and one video, taken from the latest run that attached any. Click an image to compare the pair at full size. Everything else is behind Show N more.
- Checks: the verify agent's test lines and the review agent's verdict. Limits of the proof shows what the verify agent said its proof does not cover.
- Review notes: the review agent's findings, three at a time.
- Changes: the same diff and review as the inbox pane.
Approve and Request changes at the top right work as in the inbox; Request changes needs a note.
Ready to merge
When the review-risk decision finds a change low risk and the reviewer agent has no findings, nobody needs to read the code, so no inbox item opens. The pull request appears under Ready to merge at the top of the inbox, and one click merges it as you. See Decisions.
Pull requests the merge gate did not merge
When a person marks a pull request ready for review and the merge gate is on, the gate merges the pull requests the merge-safety decision finds safe. The rest appear here with the decision's reasons, for example "CI failed." or "It changes sensitive files: lib/auth/session.ts." With the gate off, every pull request ready for review appears here. Open the item to review and merge it in Studio or on the forge; it clears when the pull request is merged or closed.
Order
The inbox-urgency decision gives each gate an urgency score when it opens. The inbox sorts by urgency, highest first, then by age, oldest first. If the decision is not available, questions get 0.7 and other gates 0.5.
Deciding
The inbox, Slack and issue replies, the API and the Kiln MCP all call the same decision code. Each decision records:
- the decision (
approve,rejectoranswer), - your answer or feedback,
- who decided and through which surface (
web,slack,linear,jira,github,mcp), - when.
The decision is added to the work item's conversation and counted as a human touch, and the audit log gets an entry. Deciding a gate that is already closed changes nothing.
A reply in Slack or on an issue or pull request decides a gate only when its author is one of the gate's assignees, or the gate has none. See Who may decide from a reply.
Only question gates take free-text answers. To decide through the inbox, the API or the MCP, your token needs the matching scope for the factory:
| Gate kind | Scope |
|---|---|
| Spec | decide:spec |
| Preview | decide:preview |
| Question | decide:question |
| Merge and custom | decide:merge |
Reminders and expiry
Gates with a nudge time post a reminder in the source thread at that interval, naming who the gate waits on. Gates with an expire time park, approve or reject on their own when it passes. The built-in spec and preview gates nudge every 24 hours and park after 72 hours. The merge gate nudges every 48 hours.
The command guard never opens an inbox item: a risky command runs inside the run's sandbox and is recorded on the run, without waiting for a person.
From the command line and MCP
kiln inbox lists your open gates. The Kiln MCP has list_inbox and decide_gate. See the CLI reference and the MCP reference.
Weekly digest
The digest groups open gates by person, oldest first, with each one's age in hours and a link to it in the inbox.
Inbox items API
GET /api/v1/inbox/items lists your inbox across factories and Studio Apps as items of seven kinds:
| Kind | When |
|---|---|
question |
An agent or the foreman asked you something. Questions can be single or multi select, with a recommended option. |
answer_question |
A question on your task was answered (for your information, for a week). |
spec_review |
A spec or plan waits for approval; also definition changes proposed by agents and self-improvement proposals, with their diff. |
pr_review |
A pull request or preview waits on you. |
studio_pr_review |
A Studio App's pull request the merge gate did not merge. It has team, appId and the gate's reasons, and goes to the team's owners and admins. |
blocked, failed |
A task of yours is stuck, when nothing else on it needs you. |
Filter with scope=mine|team, factory, kind, read=true|false and q. POST /api/v1/inbox/read, /unread, /resolve and /unresolve take {ids} (item ids, or plain gate ids). Items clear themselves when they stop being relevant: the question was answered, the spec approved, the PR merged.
Definition changes have their own actions: POST /definition-changes/{id}/approve (Approve & merge: applied at once for Kiln-managed factories, a pull request on the config repo otherwise), /request-changes (the comments go back to the agent that proposed it), /comments and /reject. Agents can never approve.