AGENTS.md · git:20261117.22a6f8b · 2026-11-17 · sha256 8ab4935f7f5ec458

AGENTS.md git:20261117.22a6f8bA

Immutable. This exact content never changes and is served at /api/v1/blob/8ab4935f7f5ec458.

# Inbox

A desktop app (Electron; macOS, Linux, Windows) that turns a GitHub review load into one queue. It's early and the owner is still finding what they want: keep changes small and easy to undo, and prefer plain code over new abstractions.

What each page does and says: [docs/ui.md](docs/ui.md). Behaviour and the API: [docs/api.md](docs/api.md). Look and layout: [docs/visual.md](docs/visual.md).

## Product principle

- **One list of what needs the owner.** The Inbox has three sections, Urgent, Standard and FYI, placed and ordered by `src/urgency.ts` (criteria, a score out of 10, thresholds). Each row is one line, says why it's there, and has at most one call to action. Everything else is sorted away by rules and the judge weighing them.
- **State lives in the desk; clients only render.** `src/desk.ts` decides what's on the queue, its order and what notifies. The window, tray, CLI, MCP and notifications all show the same state.
- **Never hold back the action an item is there for.** Anything on the Inbox can be acted on from the desk.
- **Automate before adding pages.** New behaviour becomes a rule or a setting, not a new page.
- **Mouse first.** Every action is a click named in words: a button, a link or a row's right-click menu. Only platform keys work (Esc, ⌘↵, ⌘S, Tab, ↓ and ↑ on a list, ⌘1 to ⌘4, ⌘[ and ⌘], ⌘J for Ask your agent, and / for the filter, as on GitHub), and the window names a key only in its button's tooltip, or as a chip by the button while ⌘ is held.
- **Colour only for information.** A calm palette. Colour marks CI failing, a conflict, changes requested, an AI review's risk, and calls to action (the accent). Lists are tables, sentence case, no boxed chips.
- **Problems with the system are bubbles.** The desk offline, a failed sync, the agent logged out, broken rules or a refused action show as a bubble at the window's bottom right. What belongs to an item (its CI, its AI review failing) stays on the item.
- **Look before calling a UI change done.** Run `npm run shots` and look at `.shots/` in light and dark, each theme and each size (`-- --only queue,later` shoots just those). [docs/visual.md → Checking a design change](docs/visual.md#checking-a-design-change) says what to look at; the `design-check` workflow runs it.

Pages, top to bottom in the sidebar: Inbox, Blocked, then Merging and the Archive; Ask your agent and Settings in the footer. **Hand off for merge** moves the owner's PR to Merging, where the coordinator (a background agent session the desk starts and wakes; the window calls it "your agent") gets it merged or hands it back. See [README → Coordinator](README.md#coordinator).

## Where a change goes

| To change                                         | Edit                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The desk's home (`~/.inbox`)                      | `deskHome()`, `settleHome()` (moves an old `~/.review-desk`) in `src/home.ts`                                                                                                                                                                                                                                                                                                                                                                               |
| A setting                                         | One entry in `SETTINGS` in `src/settings.ts` (`section`, `unit`, `more`). Read it as `desk.settings["section.key"]`. The UI renders it from the schema; its part: Rules → Settings                                                                                                                                                                                                                                                                          |
| Boards, rules, spaces                             | The owner's `~/.inbox/config.toml`; first-run template `defaultConfigText` in `src/config.ts`                                                                                                                                                                                                                                                                                                                                                               |
|                                                   | Built-in rules: `src/connectors/github-rules.ts` (`Connector.rules`); `parseConfig()`, `resolveRules()`, `switchBuiltIn()`, `migrateBuiltIns()` in `src/config.ts`; `Desk.switchRule()`                                                                                                                                                                                                                                                                     |
|                                                   | UI: `Rules.tsx`. [api.md → Rules](docs/api.md#rules-built-in-and-your-own)                                                                                                                                                                                                                                                                                                                                                                                  |
| A field rules can use (`me.*`, `pr.*`, …)         | `FIELDS`, `analyze()` in `src/signals.ts`; new GitHub data in `src/github/queries.ts` + `normalize.ts`                                                                                                                                                                                                                                                                                                                                                      |
| What GitHub is asked                              | `src/github/`. Reads only; writes are in `src/github/write.ts` (see Rules)                                                                                                                                                                                                                                                                                                                                                                                  |
| How a source syncs, its events, its refs          | `src/connectors/github.ts` (reconcile, notifications feed, `me()`, `init`, `refOf`, `fetchOne`, `boardIds`); `github-events.ts` (snapshot diff); the event log is `activity` in `src/store.ts`                                                                                                                                                                                                                                                              |
| When an item counts as resolved                   | `resolution()` in `src/resolve.ts`                                                                                                                                                                                                                                                                                                                                                                                                                          |
| An error (class, words, HTTP status)              | `src/errors.ts`; the rules in [docs/effect.md](docs/effect.md)                                                                                                                                                                                                                                                                                                                                                                                              |
| An HTTP route                                     | `src/server.ts` → a method on `Desk` in `src/desk.ts`                                                                                                                                                                                                                                                                                                                                                                                                       |
| A page's UI                                       | `web/src/components/`; routes in `web/src/view.ts`; wiring in `web/src/App.tsx`                                                                                                                                                                                                                                                                                                                                                                             |
| Settings' parts and views                         | `SETTINGS_PARTS`, `SETTINGS_VIEWS`, `settingsPart()`, `settingsBack()`, `SHOWN`, `DISABLED` in `web/src/view.ts`; `LEAD`, `AFTER`, `BY_KEY` in `Settings.tsx`                                                                                                                                                                                                                                                                                               |
| Styles, tokens, themes                            | `web/src/styles.css` (roles in [docs/visual.md](docs/visual.md)); themes in `src/themes.ts`, picked per device (not a desk setting) in `web/src/theme.ts`; Omarchy in `src/omarchy.ts`                                                                                                                                                                                                                                                                      |
| The sidebar, a page's head, the list beside       | `Sidebar.tsx`, `PageHead.tsx`, `Beside.tsx` (rows are `CardRow` `compact`); when it shows: `beside()` in `view.ts`, `useWide(1160)` in `App.tsx`. [visual.md → The layout](docs/visual.md#the-layout)                                                                                                                                                                                                                                                       |
| A bubble (system problem, failed action)          | `noticesOf()`, `undismissed()`, `forget()`, `withFailure()` in `web/src/notices.ts` (test: `web/test/notices.test.ts`); drawn by `Bubbles.tsx`; `.bubbles` in `styles.css`                                                                                                                                                                                                                                                                                  |
| The AI review (prompt, agents, diff)              | `src/review.ts` (`parseChunks`, `parseSteps`, `reviewOrder`, `askAgent()`); run and cached per commit by `Desk`; views in `Review.tsx` and `src/sections.ts`. [api.md → Your own agent](docs/api.md#your-own-agent)                                                                                                                                                                                                                                         |
| An issue's pre-review (screen, analysis, fix)     | `src/issue.ts` (`generateIssueReview()`, `findClone()`, `fixAskText()`); `Desk` (`pumpIssues()`, `issueView()`, `fixIssue()`, `blockAuthor()`); `IssuePre` in `Detail.tsx`. [api.md → Issues](docs/api.md#issues)                                                                                                                                                                                                                                           |
| A review document (`inbox.review/1`)              | [docs/review-format.md](docs/review-format.md); `src/doc.ts`, `src/render.ts`, `src/diagram-layout.ts`; `Desk.writeDoc()`, `submitDoc()`, `reviewDoc()`; `inbox render` in `src/cli.ts`; `inbox_doc` in `src/mcp.ts`                                                                                                                                                                                                                                        |
| What reviewers said, and Reply                    | `src/conversation.ts` (`Conversations`); `owesReply` in `src/stage.ts`; `Desk.reply()`; `Conversation.tsx`                                                                                                                                                                                                                                                                                                                                                  |
| A file's Viewed checkbox                          | `mark` in `hunksOf()`, `reviewOrder()` (`src/review.ts`); `marks` on `Section` (`src/sections.ts`); `Desk.markViewed()`, `viewed` in `Desk.reviewView()`; `markViewed()`, `isShut()` in `Review.tsx`                                                                                                                                                                                                                                                        |
| A review's sidebar: checks, reviewers, merge line | Checks: `PR_CHECKS` in `queries.ts`, `toChecks()`, `checksView()` in `src/checks.ts`, `Desk.checksOf()`. Reviewers and merge: `standings()`, `mergeLine()` in `src/stage.ts`. UI: `SidePart`, `showChecks()` in `Review.tsx`                                                                                                                                                                                                                                |
| Agents' questions for the owner (`inbox_inquire`) | `Desk.inquire()`, `answerInquiry()`, `answerRead()`, `unreadAnswers()`; MCP tools in `src/mcp.ts`; `Inquiry.tsx`; the skill's "Asking in the desk"                                                                                                                                                                                                                                                                                                          |
| Sessions that need you (Claude Code, Codex)       | `src/connectors/sessions.ts` (`look()`, `classify()`, `read()`, `kick()`); `Desk.sessionAct()`, `kickSession()`, `openSession()`; `Session.tsx`. [api.md → Sessions](docs/api.md#sessions)                                                                                                                                                                                                                                                                  |
| What a snooze can wait on                         | `Until`/`UNTIL` in `src/types.ts`; `waitable()`, `happened()` in `src/signals.ts`; `snoozeOptions()` in `web/src/format.ts`                                                                                                                                                                                                                                                                                                                                 |
| Blocked                                           | The `blocked` bucket (rules only) plus Merging's blocked PRs; `src/deps.ts` (`requiresOf`, `dependencies`, `blockedOrder`); `pr.waits` in `src/stage.ts`; `Later` in `Queue.tsx`; `treeGuides()` in `view.ts`                                                                                                                                                                                                                                               |
| A bot's PR opened for you, its attribution        | `requesterOf()`, `attributionOf()`, `onBehalf()` in `src/github/behalf.ts`; the light model's read: `Attributions` in `src/attribution.ts`. [api.md → Opened for you](docs/api.md#opened-for-you)                                                                                                                                                                                                                                                           |
| The light model (sorting, scores, questions)      | `lightModel()`, `Light` (`providers()`, `chain()`, `ask()`) in `src/light.ts`; `TIERS` in `src/settings.ts`. [api.md → The light model](docs/api.md#the-light-model)                                                                                                                                                                                                                                                                                        |
| A row's right-click menu                          | `RowMenu`, `QuestionMenu` in `RowMenu.tsx`; opened by `rowMenu()` in `App.tsx`                                                                                                                                                                                                                                                                                                                                                                              |
| Links (Copy link, `inbox://`)                     | `src/links.ts` (`placeOf`, `linkRef`); `whereIs` in `web/src/view.ts`; `openPermalink` in `electron/main.ts`; `linkArg`, `linkHash` in `electron/lib.ts`; `build.protocols` in `package.json`                                                                                                                                                                                                                                                               |
| Merging: hand-off, notes, hand-backs              | The "merging (in flight)" section of `src/desk.ts` (`waitsOn()`, `trackBlocked()`); `Inflight.tsx`. Internal names stay `inflight`                                                                                                                                                                                                                                                                                                                          |
| A row's call to action                            | `cta` in `Desk.card()`: `ready`, `reply` (`replyOnly()`), `reviewers` (`pr.unasked`, `stuckUnasked()`), `merge` (when `Desk.actions()` allows it); `reviewOptional()` in `src/stage.ts` adds Hand off for merge; `markReady()`, `askReviewers()`; drawn by `CardRow`, `Review`                                                                                                                                                                              |
| A row's stage (draft, approved, …)                | `stage()` in `src/stage.ts`, set in `Desk.card()`; drawn by `CardRow`                                                                                                                                                                                                                                                                                                                                                                                       |
| The More menu                                     | `Desk.actions()` (what an item allows), `Desk.githubAct()` (writes it); `More.tsx`                                                                                                                                                                                                                                                                                                                                                                          |
| The judge and rule weights                        | `src/judge.ts` (`buildJudgePrompt()`: its fixed instructions; `signalLine()`); `place()` (every matching rule a signal, hard rules), `weightOf()` in `src/rules.ts`; `Snapshot.judging` in `Desk.snapshot()`                                                                                                                                                                                                                                                |
| Automations                                       | `src/automations.ts` (`parseSchedule`, `dueAt`, `tick()`, `pump()`, `byRule()`, `byAsking()`, `byAgent()`, `apply()`); built-ins in `src/connectors/github-automations.ts`                                                                                                                                                                                                                                                                                  |
|                                                   | `Desk.push()`, `sort()`, `clear()`; decision model in `src/decisions.ts`; `inbox_automations` in `src/mcp.ts`; `Automations.tsx`. [api.md → Automations](docs/api.md#automations)                                                                                                                                                                                                                                                                           |
| The Inbox's sections, scores, a row's why         | `Urgency` in `src/urgency.ts` (`sectionOf()`, `score()`, `fallbackScore()`); built-in criteria in `src/connectors/github-criteria.ts`; `inbox_criteria`; `Criteria.tsx`. [api.md → Urgency](docs/api.md#urgency)                                                                                                                                                                                                                                            |
| Order within a section                            | `group` on each card from `Desk.queueCard()`; `QUEUE_GROUPS` in `src/types.ts`. Questions and sessions lead Urgent (`inquiries`, `sessions` in `QueueView`)                                                                                                                                                                                                                                                                                                 |
| A row's why, the quick-review bolt                | `Card.reason`; `Desk.quick()` (`Card.quick`)                                                                                                                                                                                                                                                                                                                                                                                                                |
| The ledger of Claude's work                       | `Jobs` in `src/jobs.ts`. [architecture.md → Claude's work](docs/architecture.md#claudes-work-srcjobsts)                                                                                                                                                                                                                                                                                                                                                     |
| The coordinator                                   | `src/coordinator.ts` (start, wake, deny list), called from `Desk`; its MCP tools in `src/mcp.ts`; what it does on a wake: `skills/inbox/SKILL.md` ("Coordinator")                                                                                                                                                                                                                                                                                           |
| Ask your agent                                    | `Desk.ask()`, `askAbout()`, `chat()`, `newChat()`; `askLine()`, `Coordinator.fresh()` in `src/coordinator.ts`; `inbox_ask`; `Chat.tsx` (`NewChat`, `NotReady`, `Examples`). [ui.md → Asking your agent](docs/ui.md#asking-your-agent)                                                                                                                                                                                                                       |
| Keys                                              | `onKey` (Esc) in `App.tsx`, `Review.tsx`, `Inquiry.tsx`; `onCapture` (`SIDE_PAGES`, `stepTo()`) in `App.tsx`; each box handles its own ⌘↵. `web/test/hints.test.ts` keeps key names out of the UI. A new key must be a platform convention                                                                                                                                                                                                                  |
| The desktop app (window, tray, hotkey)            | `electron/main.ts`; its own desk runs in `electron/desk-host.ts` (a utility process); pure helpers in `electron/lib.ts`                                                                                                                                                                                                                                                                                                                                     |
| Releases and the update notice                    | `scripts/release.ts`, `release-publish.sh` (the one publisher, run by hand or by `.github/workflows/release.yml` on GitHub's Mac runner); `Updates` in `src/updates.ts`; `latestRelease()` in `src/github/index.ts`; `updater()`, `fetchUpdate()`, `installUpdate()` in `electron/main.ts`; `selfUpdates()` in `electron/lib.ts`; the Mac's download and swap in `electron/mac-update.ts`; the line in `Sidebar.tsx`. [README → Release](README.md#release) |
| The mark and icons                                | `assets/brand/mark.svg`; `npm run icons` (`scripts/icons.ts`) writes the rest; `Mark.tsx`. [visual.md → The brand](docs/visual.md#the-brand)                                                                                                                                                                                                                                                                                                                |
| CLI / MCP                                         | `src/cli.ts` / `src/mcp.ts`; both call the running desk over HTTP via `src/client.ts`                                                                                                                                                                                                                                                                                                                                                                       |
| The iPhone app (pairing, what it renders)         | `ios/` (SwiftUI, a paired phone: its token counts as the desk's window; `ios/README.md` says how to build, test and shoot it; `npm run check` doesn't)                                                                                                                                                                                                                                                                                                      |
| Shared types                                      | `src/types.ts` (the web UI imports them too)                                                                                                                                                                                                                                                                                                                                                                                                                |
| Use from another device (Tailscale)               | `src/remote.ts`; `overTailnet()`, `remoteFetch()` in `src/server.ts`; `connectRemote()` in `src/agents.ts`; `RemoteRows` in `Settings.tsx`. [api.md → Security model](docs/api.md#security-model)                                                                                                                                                                                                                                                           |
| The first run (GitHub, picking your agent)        | `Desk.setupView()`, `checkSetup()`, `chooseAgent()`, `connectGitHub()`; words in `src/setup.ts`; `inbox setup`; `Setup.tsx`. [api.md → The first run](docs/api.md#the-first-run)                                                                                                                                                                                                                                                                            |
| The skill, and connecting agents                  | `skills/inbox/SKILL.md`; `src/agents.ts`                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Run

```bash
npm run app        # the desktop app from the repo
npm run app:dev    # the app running from this checkout; restarts on electron/ changes
npm run dev        # server --watch + Vite in a browser at :5173
npm test           # node:test, no network
npm run check      # everything CI runs: prettier, oxlint (type-aware), stylelint, tsc, knip, tests
npm run format     # prettier --write
```

`DESK_HOME` and `DESK_PORT` point any of these at a scratch home and port (default `~/.inbox` on 47823). `DESK_SENTRY=0` keeps a run out of Sentry.

### Run from a checkout

Settings → This device → Run from a checkout (`app.source`, or `DESK_SOURCE`) makes the packaged app run the desk and UI from a checkout such as `~/code/review-desk`. A merge to main then goes live without a restart, so keep main startable.

- A change under `src/` restarts only the desk (`node --watch`); the window reconnects on the same view.
- A change under `web/` hot-reloads (Vite). `http://localhost:47823` serves the same live UI (`DESK_UI_ORIGIN`).
- A change under `electron/` needs a rebuilt app (`npm run dist:mac`).
- Without a checkout, the desk serves the last `npm run build` from `web/dist`.
- Logs from both processes: `~/.inbox/live.log`. A desk that fails to start shows its last lines in the window and retries on the next change or `npm install`.
- It needs Node 22.18+ on the login shell's PATH (or in nvm, Volta, mise, asdf or fnm). Until it finds node and `node_modules`, the window says what's missing and checks again every 15 seconds.

## Rules

- **Commits.** Small commits straight on main: no branches or pull requests (the owner is effectively the only contributor). Each commit is one change that passes `npm run check`. Commit messages are one line: the owner's habit.
- **GitHub writes.** The desk writes to GitHub only through `src/github/write.ts`, and only on an explicit click in the UI (the window, or your paired phone). Its `ALLOWED` map is the complete list of mutations; adding one is a product decision, not a refactor.
  - Today's writes: Approve, Comment (PR or issue), a comment on a diff line, Reply in a conversation, Ready for review (and asking the picked reviewers), Ask reviewers, a review sidebar's remove or re-request of one reviewer on your PR (the same unrequest and rerequest, for that login), the row's Merge, and the More menu's close, reopen, convert to draft, merge, re-request review, remove me as a reviewer (the one REST write, `REST_ALLOWED`), request changes and close issue.
  - `Desk.actions()` decides which an item allows, by whose it is (`me.author`: yours, or a bot's PR opened for you; a bot's `via` line alone never counts). It refuses others with 409.
  - Nothing an agent can call (MCP, CLI) reaches the writer. A paired machine's token (kind `device`) is an agent's; a paired phone's (kind `phone`) is your hands, like the window. The read client in `src/github/client.ts` refuses any `mutation`. This holds for the desk's own tools, not against a program running as you on the desk's machine, which can forge the window's headers or pair itself as a phone (`inbox pair`): [api.md → Security model](docs/api.md#security-model).
  - Hand off for merge, Back to desk, hand-backs and Ask your agent write nothing to GitHub.
  - ⌘↵ in a box sends it like its button; no key outside a box writes. Nothing asks for a second press.
  - Every write is logged. Tests use a fake writer; live checks stub it (`startServer({ writer })`) and never touch real PRs.
- **A write shows at once, then reads back.** Anything you do that changes what a page shows (a comment, a reply, a move, a tick, a setting) draws its result before the desk answers, and then reads the object again until the desk's copy has it: never leave the old screen waiting on a sync or GitHub's lag. Rows go through `finish()` / `act()` in `App.tsx` (hidden or marked at once, then `refresh`); what you say in a review shows as yours (`sent`, `said` in `Review.tsx`) until the review re-read has it, re-read every 3 seconds meanwhile; the phone does the same (`Store`, "You · sent"). A refusal puts the screen back and keeps your words. The desk's own read of what you wrote must include it too (your own comments are part of a PR's conversation). A new write without this is a bug; its test sends it and checks the page shows it before the desk answers (`review-comment-shows` in `scripts/shots.ts`).
- **Settings stay findable and in sync.** A setting goes in the part someone would look for it under: a feature with its own name (GitHub) gets its own part, or a section of one with a name of its own (Network → Tailscale), never a row inside another. A part's name is in `SETTINGS_PARTS` (`web/src/view.ts`) and, word for word, in `SECTIONS` (`src/settings.ts`); `docs/ui.md` (its "The core's" line and a heading each) and README's Settings line list the parts in sidebar order; shots read them from `SETTINGS_PARTS`. Rename a part with fastmod over every "Settings → …" path, and add an alias in `SETTINGS_ALIAS` for its old route. `web/test/settings-sync.test.ts` fails until all of them agree; don't loosen it to pass.
- **No unchecked casts.** `typescript/no-unsafe-type-assertion` is an error outside tests: narrow unknown values (parsed JSON, SQL rows, caught errors, keys from strings) with the helpers in `src/narrow.ts` or an Effect Schema (`parseJson`, `decode`, `schemaOf<T>()`), never `as`. `exactOptionalPropertyTypes` is on: leave an optional field out rather than set it to `undefined`. An effect whose trigger it doesn't read uses `useKeyed`/`useKeyedLayout` (`web/src/keyed.ts`), never a disabled dependency rule. `test/no-casts.test.ts` counts the few known casts; the count only goes down.
- **Errors are Effects** (`effect` 4.x). A function that can fail returns `Effect.Effect<A, E>` with a tagged error from `src/errors.ts`. No `throw`/`try`/`catch` for expected failures. Background work goes through `desk.runner.fork` (the window's through `runUi`). An unawaited promise is a lint error (`.oxlintrc.json` says where). Read [docs/effect.md](docs/effect.md) before touching error handling.
- **TypeScript runs directly** (type stripping): no enums, namespaces or parameter properties; relative imports end in `.ts`; type-only imports use `import type`.
- **Comments:** one line, only for a non-obvious why.
- **Tests** for logic changes, in `test/` or `web/test/`. Tests never run a real agent: they put a fake `claude`, `codex` or `opencode` in a temp dir (`DESK_CLAUDE`, `DESK_CODEX`, `DESK_OPENCODE`). `scripts/agents-e2e/` runs Codex and OpenCode for real in a container, by hand.
- **`npm run check` must pass** (the pre-push hook runs it; CI runs it on macOS, Linux and Windows). Fix findings, don't silence them. Use `// oxlint-disable-next-line <rule> -- <reason>` only where the rule is wrong for that line. Don't loosen `.oxlintrc.json` or the tsconfig flags.
- TypeScript 7 (the Go compiler) has no JS API, so typescript-eslint can't run; type-aware linting is oxlint + tsgolint.