CLAUDE.md · diff
git:20261107.82d140e to git:20261107.3836c57
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# Review Desk
A desktop app (Electron, macOS/Linux/Windows) that turns a GitHub review load into one queue. It is early: the owner is still working out what they want, so keep changes small and easy to undo. Prefer plain code over new abstractions.
- Product principle: the main page lists only what the owner must act on, as one ordered list in a few headed parts (an agent session's question for them first: agents ask the owner through the desk with `desk_inquire`, never in chat; then a PR back to them: the coordinator handed it back, or it's ready and nobody's asked to review it (`pr.unasked`, `Desk.stuckUnasked()`, Add reviewers); then other people's PRs waiting on their review, flagged in amber; then issues and other PRs; then their own PRs: `group` on each card from `Desk.queueCard()`, Now and Today each sorted by it), one line per item (the title, quietly its repo#number, who it's from and a PR's stage, its age, and at most one call to action naming the action, e.g. "Ready for review" on their own draft or "Reply" on their PR whose only action is answering someone; no why, AI gist or chips). PRs handed off (Hand off for merge) live in Merging, never on the main page; the coordinator (a background Claude Code session the desk starts and wakes, README → Coordinator; the window calls it your agent) gets them merged, and one comes back only when it hands it back. Anything on the main page can be acted on from the desk: the desk never holds back the action an item is there for (a red draft still offers Ready for review: CI is the coordinator's to fix once it's ready). The sidebar, top to bottom: Inbox (the main page), Blocked (what can't move until something else happens: a PR it needs merging first, a review), FYI (what was sorted away, snoozed or muted), then under a hairline Merging and the Archive (what's done: yours, or resolved by the world). Maximize automation: new things become rules or settings, not new pages. State stays on the desk (`src/desk.ts` decides what's on the queue, its order and what notifies; clients only render), so the tray, MCP and notifications agree and another client could render the same. Design: an informational app with a calm palette and no highlighter; colour only where it carries information (CI failing, a merge conflict, changes requested, an AI review's risk) and on calls to action (the accent: filled on the one to press, tinted on a row's); lists are tables: compact type (15px titles, 13px meta), rows on one sheet with hairlines between them, a small PR/Issue label, and meta in columns that line up row to row; sentence case, no boxed chips; mouse first: every action is a click named in words (a button, a link, or a row's right-click menu); the window names no key, and only the platform's keys work (Esc, ⌘↵ in a box that sends, Enter in the chat, ⌘S, Tab, menu arrows), each named only in its button's tooltip. Themes are CSS token sets picked per device (Settings → Appearance, kept by the desktop app, or in localStorage in a browser), not desk settings. After any UI change run `npm run shots` and look at `.shots/` in light and dark and each theme (`-- --only queue,later` shoots just those while iterating); don't call a design change done from code alone.
+ Product principle: the main page lists only what the owner must act on, as one ordered list in a few headed parts (an agent session's question for them first: agents ask the owner through the desk with `desk_inquire`, never in chat; then a PR back to them: the coordinator handed it back, or it's ready and nobody's asked to review it (`pr.unasked`, `Desk.stuckUnasked()`, Add reviewers); then other people's PRs waiting on their review, flagged in amber; then issues and other PRs; then their own PRs: `group` on each card from `Desk.queueCard()`, Now and Today each sorted by it), one line per item (the title, quietly its repo#number, who it's from and a PR's stage, its age, and at most one call to action naming the action, e.g. "Ready for review" on their own draft or "Reply" on their PR whose only action is answering someone; no why, AI gist or chips). PRs handed off (Hand off for merge) live in Merging, never on the main page; the coordinator (a background Claude Code session the desk starts and wakes, README → Coordinator; the window calls it your agent) gets them merged, and one comes back only when it hands it back. Anything on the main page can be acted on from the desk: the desk never holds back the action an item is there for (a red draft still offers Ready for review: CI is the coordinator's to fix once it's ready). What was sorted away is under Later; what can't move until something else happens (a PR it needs merging first, a review) is under Blocked; what's done (yours, or resolved by the world) is in the Archive. Maximize automation: new things become rules or settings, not new pages. State stays on the desk (`src/desk.ts` decides what's on the queue, its order and what notifies; clients only render), so the tray, MCP and notifications agree and another client could render the same. Design: an informational app with a calm palette and no highlighter; colour only where it carries information (CI failing, a merge conflict, changes requested, an AI review's risk) and on calls to action (the accent: filled on the one to press, tinted on a row's); lists are tables: compact type (15px titles, 13px meta), rows on one sheet with hairlines between them, a small PR/Issue label, and meta in columns that line up row to row; sentence case, no boxed chips; mouse first: every action is a click named in words (a button, a link, or a row's right-click menu); the window names no key, and only the platform's keys work (Esc, ⌘↵ in a box that sends, Enter in the chat, ⌘S, Tab, menu arrows), each named only in its button's tooltip. Themes are CSS token sets picked per device (Settings → Appearance, kept by the desktop app, or in localStorage in a browser), not desk settings. After any UI change run `npm run shots` and look at `.shots/` in light and dark and each theme (`-- --only queue,later` shoots just those while iterating); don't call a design change done from code alone.
## Where a change goes
| To change | Edit |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A setting (Settings page, `desk settings`) | One entry in `SETTINGS` in `src/settings.ts`; read it via `desk.settings["section.key"]`. The UI renders it from the schema |
| Boards, rules, spaces | `~/.review-desk/config.toml` (the Rules page), or the first-run template `defaultConfigText` in `src/config.ts` |
| A field rules can use (`me.*`, `pr.*`, …) | `FIELDS` and `analyze()` in `src/signals.ts`; any new GitHub data in `src/github/queries.ts` + `normalize.ts` |
| What GitHub is asked | `src/github/` (the read client refuses `mutation`; the only writes, approve, a reply or comment, a comment on a line, ready for review and the More menu's, are in `src/github/write.ts`) |
| How a source syncs, what counts as an event | `src/connectors/` (`github.ts`: reconcile and the notifications feed; `github-events.ts`: the pure snapshot diff), the event log in `activity` (`src/store.ts`) |
| When an item counts as resolved | `resolution()` in `src/resolve.ts` |
| An HTTP route | `src/server.ts` → a method on `Desk` in `src/desk.ts` |
| The queue / review / Settings UI | `web/src/components/` (Queue and Later, CardRow, Review, Inflight, Settings, Rules, Policy), routes in `web/src/view.ts`, wiring in `web/src/App.tsx`, styles and theme tokens in `web/src/styles.css`, the per-device theme in `web/src/theme.ts` |
| The AI review (prompt, agents, diff fetch) | `src/review.ts`; kept per commit and run in the background by `Desk` in `src/desk.ts`. Every agent run is the owner's own `claude` (no `--model`, no API key); see api.md's "Your own Claude Code" |
| What reviewers said: what waits on you, Claude's read | `src/conversation.ts` (the rule, the prompt, `Conversations` fetching and reading in the background; `owesReply`, for the row's Reply, in `src/stage.ts`); `Desk.reply()` sends yours; `web/src/components/Conversation.tsx` |
| Agents' questions for the owner (`desk_inquire`) | `Desk.inquire()`, `answerInquiry()` in `src/desk.ts`, the routes in `src/server.ts`, the MCP tools in `src/mcp.ts`; the rows and the page (`InquiryPage`, `#/inquiry/<id>`) in `web/src/components/Inquiry.tsx`, led by `inquiries` in `QueueView`; what a question must carry in `desk_inquire`'s description and the skill's "Ask the user in their desk" |
| What a snooze can wait on (CI passes, new commits, …) | `Until`/`UNTIL` in `src/types.ts`; `waitable()` (what an item offers, the card's `wake_on`) and `happened()` in `src/signals.ts`; `act()` and `compute()` in `src/desk.ts`; the menus read `snoozeOptions()` in `web/src/format.ts` |
| Blocked (what can't move yet) | the `blocked` bucket, filled by rules (template: `defaultConfigText`; `final` in `place()`), and Merging's blocked PRs; the facts in `src/deps.ts` (`requiresOf`, `dependencies`, `blockedOrder`), into `pr.*` by `Desk.compute()`; `pr.waits` in `src/stage.ts`; `QueueView.sections.blocked`, `#/blocked` in `web/src/view.ts`, `Later` in `Queue.tsx` |
| A row's right-click menu | `web/src/components/RowMenu.tsx`, opened by `rowMenu()` in `web/src/App.tsx` |
| Merging: hand-off and back, notes, hand-backs, what it waits on | `Desk` in `src/desk.ts` (the "merging (in flight)" section and `waitsOn()`; `compute()` keeps them off the queue and puts hand-backs on top; `trackBlocked()`, the unblock wake), `web/src/components/Inflight.tsx`; internal names stay `inflight` |
| A row's call to action (Ready for review, Reply, Add reviewers) | `cta` in `Desk.card()` (`replyOnly()` for Reply; `pr.unasked` in `src/signals.ts` and `stuckUnasked()` for Add reviewers), `markReady()` and `askReviewers()` in `src/desk.ts`, rendered by `CardRow` and `Review` |
| A row's stage (draft, waiting for review, approved…) | `stage()` in `src/stage.ts` (`verdicts()` is Merging's too), set with `by` in `Desk.card()`, rendered by `CardRow` |
| The More menu (a review's; a row's menu has the same writes) | `Desk.actions()` decides what an item allows (`actions` on its card), `Desk.githubAct()` writes it; `web/src/components/More.tsx` (in a review: Done, Ask Claude to review it, Open on GitHub, then the writes) |
| The policy and the judge (prompt, starter, cap) | `~/.review-desk/policy.md` (Settings → Policy), `DEFAULT_POLICY` while it's empty; `src/judge.ts`, its answers reach `classify()` in `src/rules.ts` through `Desk.compute()`; hard rules in `place()` |
| Automations (schedules, runs, what lands on the desk) | `src/automations.ts` (`parseSchedule`, `dueAt`, the run and its deny list, the prompt), `Desk.push()` and `hold()` in `src/desk.ts`, the routes in `src/server.ts`, `desk_automations` in `src/mcp.ts`; `web/src/components/Automations.tsx` (Settings → Automations) |
| The coordinator (starting, waking, what it does) | `src/coordinator.ts` (`claude --bg` start, `--resume --bg` wakes, the deny list), wired in `Desk.start()`, `record()` and `act()`; what it does on a wake in `skills/review-desk/SKILL.md` ("Coordinator"); its MCP tools in `src/mcp.ts` |
| The owner's asks (Ask your agent) | `Desk.ask()`, `askAbout()`, `askPlace()` in `src/desk.ts`, `askLine()` in `src/coordinator.ts`, `desk_ask` in `src/mcp.ts`; the window's side in `web/src/components/Chat.tsx` and docs/ui.md → Asking your agent |
| Keys | Esc in `onKey` in `web/src/App.tsx`, `Review.tsx` and `Inquiry.tsx`, each box's own ⌘↵/Esc; `web/test/hints.test.ts` keeps `<kbd>` chips and key names out of the window's strings and the desk's; a new key must be a platform convention, named in its button's tooltip |
| The desktop app (window, tray, hotkey, login item) | `electron/main.ts`; pure helpers in `electron/lib.ts` |
| CLI / MCP | `src/cli.ts` / `src/mcp.ts` (both talk HTTP to the running desk via `src/client.ts`) |
| Shared types | `src/types.ts` (the web UI imports these too) |
| The skill | `skills/review-desk/SKILL.md`; connecting agents to the desk in `src/agents.ts` |
## Run
```bash
npm run app # the desktop app from the repo
npm run app:dev # the desktop app running from this checkout (below); 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; the default is `~/.review-desk` on 47823. `DESK_SENTRY=0` keeps a run out of Sentry.
Run from a checkout: Settings → Desktop app → Run from a checkout (`app.source`, or `DESK_SOURCE`) set to `~/code/review-desk` makes the packaged app run from that checkout, so a merge to main lands live without a restart (keep main startable). The app keeps its window, tray, hotkey and login item, and runs the desk from the checkout with `node --watch` (a change under `src/` restarts only the desk; the window stays on its view and reconnects) and the UI on a Vite dev server (a change under `web/` is hot reload). `http://localhost:47823` then always serves that current UI too, hot reload included (the desk passes the app's Vite server through, `DESK_UI_ORIGIN`), so a browser tab or Claude's browser pane keeps one address across merges and app restarts; a tab reloads itself when the desk restarts. Otherwise the desk serves the last `npm run build` from `web/dist`. A change under `electron/` needs a rebuilt app (`npm run dist:mac`). A desk that fails to start shows its last lines in the window and starts again on the next change or `npm install`; both processes' output is in `~/.review-desk/live.log`. It needs Node 22.18 or newer on your login shell's PATH (or where nvm, Volta, mise, asdf or fnm keep it, for a shell too slow to answer); until it finds node (and `node_modules`, in a folder that is a checkout), the window says what's missing and the app looks again every 15 seconds, never running its own desk in its place.
## Rules
- The desk writes to GitHub only through `src/github/write.ts`, and only on an explicit user action in the UI (today: approve, **Approve** in a PR's review; a comment on the PR, **Comment** in its review, or on an issue, **Comment** on it opened in place; a comment on a line of its diff, the `+` by the line's number, then Comment; **Reply** under a conversation in a PR's review; **Ready for review** on your own draft's row or in its review, where it also asks the reviewers you picked; **Ask reviewers** in the review of your ready PR nobody's asked to review; the More menu in a review, or the same writes in a row's right-click menu: ready for review on your draft, close, convert to draft, merge now (pinned to the head the desk judged ready) and reopen a PR you opened, close an issue you opened or are assigned, and request changes on someone else's PR in its review). ⌘↵ in the box you wrote in sends it like its button; no key outside a box writes anything. Ask your agent writes nothing to GitHub: the chat goes only to your agent, and nothing moves between a box that posts and the chat. Nothing asks for a second press. What you do in the desk takes the item off its list at once (done until someone else acts, into the Archive; a hand-off into Merging) while a review stays open, saying what you did and where it went, with a spinner until GitHub has it, and back if GitHub refuses; Approve and Hand off for merge are green. Which of the More menu's an item allows is the desk's call (`Desk.actions()`), on the real author: a bot's `via` line never unlocks one; it refuses any other with 409. Its `ALLOWED` map is the complete list of mutations; adding one is a product decision, not a refactor. Hand off for merge, Back to desk and a hand-back write nothing; the coordinator is the owner's own Claude Code session, which the desk starts and wakes but doesn't run. Every write is logged and recorded in the action log. Nothing an agent can call (MCP tools, the CLI) reaches it, and the read client in `src/github/client.ts` keeps refusing every `mutation`. Tests use a fake write client; live checks stub it (`startServer({ writer })`) and never touch real PRs.
- Node runs the `.ts` files 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.
- Add or update a test in `test/` (or `web/test/`) for logic changes. Tests never run a real agent: the judge and coordinator tests put a fake `claude` in a temp dir.
- `npm run check` must pass before you're done (the pre-push hook runs it; CI runs it on macOS, Linux and Windows). Fix findings, don't silence them: an inline `// 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.