crit: Instructions file for Codex

Crit — Development Guide

Single-binary Go CLI that opens a browser-based UI for reviewing code changes and markdown files with GitHub PR-style inline commenting. Multi-file review with git diff rendering and structured review file output for AI coding agents.

Project map

crit/
├── cmd/crit/            # package main — thin CLI (main.go, cli_*.go, wire.go)
├── internal/            # Core logic packages (daemon, server, session, github, share, vcs, …)
├── web/                 # Embedded frontend assets (Go package webassets; embed.go)
│   ├── index.html       # HTML shell — code-review OR live-mode script fork
│   ├── app.js           # Code-review mode JS
│   ├── live-mode*.js    # Live-mode modules
│   ├── crit-agent.js / agent-*.js / agent-marker.css  # Injected iframe scripts
│   ├── crit-*.js        # Shared renderer, SSE, draft, comment UI modules
│   ├── style.css / style-live.css / theme.css
│   ├── __tests__/       # Node.js unit tests (node --test)
│   ├── pierre/          # Vendored @pierre/diffs + Shiki (split ESM, gzip; scripts/build-pierre.mjs)
│   └── *.min.js         # Vendored markdown-it, DOMPurify, mermaid, diff-match-patch
├── integrations/        # Drop-in config files for AI coding tools (claude-code, cursor, aider, …)
├── test/                # Test harnesses, E2E, roundtrip docs, shared fixtures
├── Makefile
├── package.json
└── copy-deps.js         # Copies npm deps into web/ for embedding

Key architecture decisions

1. All frontend assets embedded via Go's embed.FS — produces a true single binary
2. No frontend build step — vanilla JS, no npm/webpack/framework. npm is only for fetching vendor libs.
3. Two modes: "git" mode (auto-detect from git) and "files" mode (explicit file arguments)
4. markdown-it for parsing — chosen because it provides token.map (source line mappings per block)
5. Block-level splitting — lists, code blocks, tables, blockquotes split into per-item/per-line/per-row blocks so each source line is independently commentable
6. Diff rendering is @pierre/diffs — the review list (git and files mode) is one Pierre CodeView: virtualization, sticky headers, Shiki highlighting in a worker pool, word diffs, split/unified, context expansion. Crit supplies the file header, comments/forms as annotations, keyboard focus and jumps. Rendered markdown (Document view) is Crit's line-block document inside a Pierre item. Story chapters use Pierre FileDiff. See docs/frontend-js.md.
7. Comments reference source line numbers — stored in ~/.crit/reviews/<key>.json with per-file sections
8. Real-time output — review file written on every comment change (200ms debounce)
9. File watching — git mode polls git status --porcelain; files mode polls mtimes; reloads via SSE
10. Localhost by default — server binds to 127.0.0.1 (no CORS headers needed). Non-loopback --host / CRIT_HOST / global host, or any public_url, require --allow-unauthenticated-network / CRIT_ALLOW_UNAUTHENTICATED_NETWORK=1 (Crit has no network auth).
11. Two-level config — ~/.crit.config.json (global) merged with .crit.config.json (project), CLI flags override both. agent_cmd, auth_token, share_url, and plan_approve_mode are global-only (prevents malicious repos from hijacking agent commands, redirecting share requests, or weakening Claude Code permissions)
12. Headless CLI comment — crit comment writes directly to the review file without starting the server; SSE notifies any running server
13. Comment threading — comments support nested replies and a resolved boolean. Review file schema nests replies inside each comment's replies array.
14. Centralized review storage — ~/.crit/reviews/<key>.json keyed by cwd + branch (git mode) or cwd + args (file mode)
15. VCS abstraction — vcs.go defines a backend interface; git_vcs.go, sapling.go, and jj.go are the implementations. Auto-detected, overridable via --vcs flag or vcs config key. Subcommands not yet threaded through (see TODO at main.go:1826).
16. Pluggable renderers — web/crit-renderers.js registry; two registration kinds: kind: 'fence' (by info string, langs) and kind: 'file' (by glob, paths, <label> / Source toggle, viewMode: 'rendered'). Built-in mermaid (crit-renderer-mermaid.js) covers ```mermaid, *.mermaid, *.mmd, and injects mermaid.min.js only on the first diagram (not in index.html). New renderers ship in web/ (no external script loading). See docs/renderers.md.
17. Focus mode — sub-views over the file list: file focus, range focus (--range A..B), stacked focus (range layer in a stacked PR). Lives in focus_*.go and /api/focus.