Imported from jonfriesen/codereview.dog (AGENTS.md). Install upstream with npx skills add jonfriesen/codereview.dog. Copyright stays with the author.

codereview.dog — Agent Guide

codereview.dog is an AI-powered pull request review tool. It transforms GitHub PR diffs into scroll-based narrative documents with AI-generated explanations, interactive symbol references, and per-section verdicts.

Documentation

Read these before starting any task:

• docs/prd.md — Product requirements document. Defines the problem, product concept, all functional/non-functional requirements, and architecture.
• docs/roadmap.md — Ordered task checklist (46 tasks, 9 phases). Tasks must be completed in order — each depends on prior tasks.
• docs/tasks/NN-name.md — Detailed spec for each task. Contains objective, context, requirements, file structure, acceptance criteria, and PRD references. Read the relevant task file before implementing.
• mock/ — Working prototype with all UI patterns implemented. Use as the reference for visual design, component structure, data shapes, and CSS. See mock/AGENTS.md for mock-specific details.

Project Structure

server/             # Go backend (created in task 01)
  cmd/server/       # Entry point (main.go)
  internal/         # Private packages
    api/            # HTTP handlers
    auth/           # OAuth + session + middleware
    github/         # GitHub API client
    diff/           # Unified diff parser
    llm/            # Anthropic Claude client
    analysis/       # AI analysis orchestrator + prompts
    db/             # SQLite + migrations
  Makefile

web/                # React frontend (created in task 03)
  src/
    pages/          # Page components (ReviewPage, LoginPage)
    components/     # Shared UI components
    auth/           # Auth context + route guard
    lib/            # API client, utilities
  vite.config.js

mock/               # Standalone Vite+React prototype (reference only)
  src/
    PRReviewApp.jsx # All components, styles, mock data (~2100 lines)

docs/               # Specifications
  prd.md
  roadmap.md
  tasks/

Tech Stack

Key Data Shapes

The AI analysis pipeline produces JSON matching these shapes. The mock has working examples of all of them.

Analysis {
  overview: string                         // 2-3 sentence PR summary
  sections: Section[]                      // Logical groupings of changes
  symbol_defs: { [name]: SymbolDef }       // Hover/click symbol data
}

Section {
  id: string                               // e.g. "section-0"
  number: number                           // 1-indexed
  title: string                            // e.g. "The StreamHandler Abstraction"
  files: [{ file, status, linesChanged }]  // File badges
  intro: Part[]                            // Short 1-2 sentence intro
  diffs: Diff[]                            // Code diffs with annotations
}

Diff {
  file: string                             // e.g. "pkg/stream/handler.go"
  status: "added" | "modified" | "deleted"  
  linesChanged: string                     // e.g. "+78 -0"
  lines: Line[]                            // Diff lines
  annotations: Annotation[]                // Interleaved callouts
}

Line {
  type: "add" | "del" | "ctx"              // Added, deleted, context
  number: number                           // Line number
  content: string                          // Code text
}

Annotation {
  afterLine: number                        // Show after this line (0 = before all)
  content: Part[]                          // Rich text with symbols
}

Part {
  type: "text" | "symbol"                  
  content?: string                         // For type "text"
  name?: string                            // For type "symbol" — key into symbol_defs
}

SymbolDef {
  kind: string                             // "struct", "interface", "func", "type"
  package: string                          // e.g. "pkg/stream", "io", "context"
  definition: string                       // Go source code of the definition
  href?: string                            // External docs URL (pkg.go.dev)
  section?: number                         // Section index where defined (internal symbols)
}

Design System

The UI uses a GitHub-dark aesthetic. All colors and styles are in the mock's const CSS block (~300 lines starting around line 650 of mock/src/PRReviewApp.jsx).

Conventions

Go Backend

• Use internal/ for all packages — nothing is exported outside the module
• Errors: wrap with fmt.Errorf("context: %w", err) for chain
• Logging: log/slog structured logging
• Config: environment variables loaded via the config package (task 04)
• HTTP responses: always JSON with Content-Type: application/json
• Error responses: {"error": "description"} with appropriate status codes
• Tests: table-driven tests, httptest for handler tests

React Frontend

• Plain JSX (no TypeScript) — but use JSDoc comments for complex prop shapes
• One component per file in src/components/
• CSS: self-contained per component, injected via <style> in <head> using useEffect (see mock pattern)
• State: React hooks (useState, useCallback, useMemo, useRef)
• React must be imported as a default import (explicit React.Fragment usage in the codebase)
• API calls: use the apiFetch helper from src/lib/api.js — it handles 401 redirects

Git

• Commit after each task with a descriptive message
• Update docs/roadmap.md to check off completed tasks: [ ] → [x]
• If a task requires changes to a prior task's files, note what changed and why

Building & Running

Always use the root Makefile for building, running, and testing. Do not cd into subdirectories to build individually.

make          # Build everything (web → server/static → Go binary)
make deploy   # Build + restart systemd service (preferred for testing)
make dev      # Build + start the server in foreground
make test     # Go tests (-race) + web eslint
make lint     # go vet + eslint
make clean    # Remove build artifacts

The default make target builds the web frontend, copies the output to server/static/, then compiles the Go binary. make dev does this and starts the server.

Server Management

The server runs as a systemd service (srv). After any code change:

make deploy              # Build everything + restart service

Manual management:

sudo systemctl restart srv       # Restart
sudo systemctl status srv        # Check status
journalctl -u srv -f             # Tail logs

Important: Do NOT use tmux, &, or nohup to run the server — always use make deploy or systemctl. This avoids zombie processes holding the port.

Mock prototype (no backend needed):

cd mock && npm install && npm run dev
# → http://localhost:8000

Environment

• OS: Linux (amd64)
• Go: 1.22+
• Node: 18
• SQLite: via modernc.org/sqlite (no CGO)
• External services: GitHub API, Anthropic Claude API
• Dev URL: https://codereview-dog.exe.xyz:<port>/