crit AGENTS.md

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)
│   └── *.min.js         # Vendored markdown-it, highlight.js, mermaid
├── 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 hunk rendering — code files show git diffs with dual gutters (old/new line numbers)
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. 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.