A local CLI tool that starts a server offering a web interface to review staged code changes, similar to GitHub PR review but fully local. Optimized for agent-assisted code review workflows.
| Layer | Technology | Rationale |
|---|---|---|
| Runtime | Node.js 24+ | Native TypeScript support, stable node:sqlite |
| Language | TypeScript 5.x | Type safety, better maintainability |
| Backend | Fastify 5.x | Fast, schema-based validation, OpenAPI support |
| Database | SQLite (node:sqlite) | Zero deps, native Node.js, synchronous API |
| Frontend | React 18 + Vite | Modern tooling, fast HMR, easy embedding |
| Styling | Tailwind CSS | Utility-first, minimal CSS maintenance |
| Diff Engine | diff2html + diff | Battle-tested diff visualization |
| Syntax Highlighting | Shiki | VSCode-quality highlighting, many themes |
| CLI | node:util parseArgs | Zero deps, native Node.js argument parsing |
| Server Testing | node:test | Zero deps, native Node.js, fast |
| Frontend Testing | Vitest + Testing Library | Fast, Vite-integrated, excellent DX |
| E2E Testing | Playwright | Cross-browser, reliable, great debugging |
| API Docs | @fastify/swagger | Auto-generated OpenAPI from schemas |
local-code-reviewer/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── vitest.config.ts
├── tailwind.config.js
├── index.html # Vite entry point
├── src/
│ ├── cli/ # CLI entry points
│ │ ├── index.ts # Main CLI entry
│ │ ├── commands/
│ │ │ ├── serve.ts # Start server command
│ │ │ ├── list.ts # List reviews command
│ │ │ ├── export.ts # Export review command
│ │ │ └── todo.ts # Todo management command
│ │ └── utils/
│ │ └── open-browser.ts
│ │
│ ├── server/ # Fastify backend
│ │ ├── index.ts # Server entry & plugin registration
│ │ ├── app.ts # Fastify app factory
│ │ ├── config.ts # Server configuration
│ │ ├── plugins/
│ │ │ ├── static.ts # Serve embedded SPA
│ │ │ ├── cors.ts # CORS for development
│ │ │ ├── auth.ts # Optional token authentication
│ │ │ └── swagger.ts # OpenAPI documentation
│ │ ├── routes/
│ │ │ ├── reviews.ts # Review CRUD endpoints
│ │ │ ├── comments.ts # Comment endpoints
│ │ │ ├── diff.ts # Diff generation endpoints
│ │ │ ├── todos.ts # Todo CRUD endpoints
│ │ │ └── export.ts # Export endpoints
│ │ ├── services/
│ │ │ ├── git.service.ts # Git operations
│ │ │ ├── diff.service.ts # Diff parsing & formatting
│ │ │ ├── review.service.ts # Review business logic
│ │ │ ├── comment.service.ts
│ │ │ └── export.service.ts # Markdown export
│ │ ├── repositories/
│ │ │ ├── review.repo.ts # Review data access
│ │ │ ├── comment.repo.ts # Comment data access
│ │ │ └── todo.repo.ts # Todo data access
│ │ ├── db/
│ │ │ ├── index.ts # Database connection
│ │ │ ├── schema.ts # Table definitions
│ │ │ └── migrations/ # Schema migrations
│ │ └── schemas/ # JSON schemas for validation
│ │ ├── review.schema.ts
│ │ └── comment.schema.ts
│ │
│ ├── web/ # React frontend
│ │ ├── main.tsx # React entry point
│ │ ├── App.tsx # Root component
│ │ ├── api/
│ │ │ └── client.ts # API client (fetch wrapper)
│ │ ├── components/
│ │ │ ├── layout/
│ │ │ │ ├── Header.tsx
│ │ │ │ ├── Sidebar.tsx
│ │ │ │ └── Layout.tsx
│ │ │ ├── diff/
│ │ │ │ ├── DiffView.tsx # Main diff container
│ │ │ │ ├── DiffFile.tsx # Single file diff
│ │ │ │ ├── DiffLine.tsx # Single line with gutter
│ │ │ │ ├── LineComment.tsx # Inline comment display
│ │ │ │ └── CommentForm.tsx # Add/edit comment form
│ │ │ ├── review/
│ │ │ │ ├── ReviewList.tsx # List of saved reviews
│ │ │ │ ├── ReviewHeader.tsx # Review metadata
│ │ │ │ └── ReviewSummary.tsx # Stats & overview
│ │ │ ├── suggestions/
│ │ │ │ ├── SuggestionBlock.tsx # Code suggestion display
│ │ │ │ └── SuggestionEditor.tsx # Create suggestions
│ │ │ ├── todos/
│ │ │ │ ├── TodoPanel.tsx # Todo list panel/drawer
│ │ │ │ ├── TodoItem.tsx # Single todo item
│ │ │ │ └── TodoInput.tsx # Add todo input
│ │ │ └── ui/ # Reusable UI components
│ │ │ ├── Button.tsx
│ │ │ ├── Modal.tsx
│ │ │ ├── Badge.tsx
│ │ │ └── Spinner.tsx
│ │ ├── hooks/
│ │ │ ├── useReview.ts
│ │ │ ├── useComments.ts
│ │ │ ├── useDiff.ts
│ │ │ └── useTodos.ts
│ │ ├── stores/ # State management (Zustand)
│ │ │ ├── review.store.ts
│ │ │ └── ui.store.ts
│ │ ├── types/
│ │ │ └── index.ts # Shared TypeScript types
│ │ └── styles/
│ │ └── globals.css
│ │
│ └── shared/ # Shared between server & web
│ └── types.ts # API types, DTOs
│
├── scripts/
│ └── build.ts # Build script for embedding SPA
│
├── tests/
│ ├── server/ # node:test for backend
│ │ ├── services/
│ │ ├── repositories/
│ │ └── routes/
│ ├── web/ # Vitest for React components
│ │ └── components/
│ ├── e2e/ # Playwright E2E tests
│ │ ├── review.spec.ts # Review creation flow
│ │ ├── comments.spec.ts # Commenting flow
│ │ └── export.spec.ts # Export functionality
│ └── fixtures/
│ └── sample-diffs/
│
├── playwright.config.ts # Playwright configuration
│
└── dist/ # Build output
├── cli/ # Compiled CLI
├── server/ # Compiled server
└── web/ # Bundled SPA assets
-- Reviews table: snapshots of changes (staged, branch, or commits)
CREATE
8000
TABLE reviews (
id TEXT PRIMARY KEY, -- UUID
repository_path TEXT NOT NULL, -- Absolute path to repo
base_ref TEXT, -- Git ref (HEAD, commit SHA)
source_type TEXT DEFAULT 'staged', -- 'staged' | 'branch' | 'commits'
source_ref TEXT, -- Branch name, commit SHAs, etc.
snapshot_data TEXT NOT NULL, -- JSON: serialized diff data
status TEXT DEFAULT 'in_progress', -- in_progress | approved | changes_requested
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT DEFAULT CURRENT_TIMESTAMP
);
-- Comments table: line and file-level comments
CREATE TABLE comments (
id TEXT PRIMARY KEY, -- UUID
review_id TEXT NOT NULL,
file_path TEXT NOT NULL, -- Relative path in repo
line_number INTEGER, -- NULL for file-level comments
line_type TEXT, -- 'added' | 'removed' | 'context'
content TEXT NOT NULL, -- Markdown content
suggestion TEXT, -- Optional code suggestion
resolved INTEGER DEFAULT 0, -- Boolean: 0 or 1
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE
);
-- Todos table: task tracking for reviews
CREATE TABLE todos (
id TEXT PRIMARY KEY, -- UUID
content TEXT NOT NULL, -- Todo text content
completed INTEGER DEFAULT 0, -- Boolean: 0 or 1
review_id TEXT, -- Optional: link to specific review
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE
);
-- Indexes for common queries
CREATE INDEX idx_comments_review ON comments(review_id);
CREATE INDEX idx_comments_file ON comments(review_id, file_path);
CREATE INDEX idx_reviews_status ON reviews(status);
CREATE INDEX idx_reviews_created ON reviews(created_at DESC);
CREATE INDEX idx_todos_review ON todos(review_id);
CREATE INDEX idx_todos_completed ON todos(completed);| Method | Endpoint | Description |
|---|---|---|
GET |
/api/reviews |
List all reviews (paginated) |
POST |
/api/reviews |
Create review from staged changes |
GET |
/api/reviews/:id |
Get review with full diff data |
PATCH |
/api/reviews/:id |
Update review (title, status, description) |
DELETE |
/api/reviews/:id |
Delete review and all comments |
GET |
/api/reviews/:id/export |
Export review as markdown |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/reviews/:id/comments |
List comments for review |
POST |
/api/reviews/:id/comments |
Add comment to review |
PATCH |
/api/comments/:id |
Update comment content |
DELETE |
/api/comments/:id |
Delete comment |
POST |
/api/comments/:id/resolve |
Mark comment as resolved |
POST |
/api/comments/:id/unresolve |
Mark comment as unresolved |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/diff/staged |
Get current staged changes |
GET |
/api/diff/files |
List files with staged changes |
GET |
/api/diff/branches |
Compare two branches (?from=<ref>&to=<ref>) |
GET |
/api/diff/commits |
Get diff for specific commits (?commits=<sha1>,<sha2>) |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/git/branches |
List all branches |
GET |
/api/git/commits |
List recent commits (?limit=20) |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/todos |
List all todos (filter: ?review_id=<id>, `?completed=0 |
POST |
/api/todos |
Create a new todo |
PATCH |
/api/todos/:id |
Update todo content or completed status |
DELETE |
/api/todos/:id |
Delete a todo |
POST |
/api/todos/:id/toggle |
Toggle completed status |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Server health check |
GET |
/api/info |
Repository info (name, branch, etc.) |
Start the review server and open web interface.
code-review serve [options]
Options:
-p, --port <number> Port to run server on (default: 3847)
--no-open Don't auto-open browser
-h, --host <string> Host to bind to (default: localhost)
--auth <token> Enable token authentication (optional)When --auth is provided:
- All API endpoints require
Authorization: Bearer <token>header - Web interface prompts for token on first visit (stored in localStorage)
- Token can also be set via
CODE_REVIEW_TOKENenvironment variable
List all saved reviews for the current repository.
code-review list [options]
Options:
--status <status> Filter by status (in_progress|approved|changes_requested)
--json Output as JSONExport a review to markdown.
code-review export <review-id> [options]
Options:
-o, --output <file> Output file path (default: stdout)Manage todo items for tracking tasks during review.
code-review todo <subcommand> [options]
Subcommands:
add <content> Add a new todo item
list List all todos
done <id> Mark todo as completed
undone <id> Mark todo as not completed
remove <id> Delete a todo
clear Remove todos (use with --done to clear completed)
Options:
--review <id> Scope todo to a specific review
--done Filter to show only completed todos (list) or clear completed (clear)
--pending Filter to show only pending todos
--json Output as JSONExamples:
# Add a todo
code-review todo add "Fix the type error in utils.ts"
# List all pending todos
code-review todo list --pending
# Mark todo as done (use first few characters of ID)
code-review todo done abc123
# Clear all completed todos
code-review todo clear --done
# Add a todo linked to a specific review
code-review todo add "Address comment on line 42" --review <review-id>Goal: Basic CLI + server + database setup
-
Initialize project with TypeScript configuration
- Configure
tsconfig.jsonfor Node.js 20+ with ES modules - Set up path aliases (
@/server,@/web,@/shared)
- Configure
-
Set up Fastify server skeleton
- Create app factory with plugin registration
- Add health check endpoint
- Configure CORS for development
-
Implement SQLite database layer
- Set up node:sqlite connection (DatabaseSync)
- Create version-based migration system using PRAGMA user_version
- Implement repository pattern for data access
-
Build CLI with node:util parseArgs
- Implement
servecommand with port/host options - Add browser auto-open functionality
- Implement
listcommand (basic)
- Implement
Goal: Parse staged changes and generate diffs
-
Implement Git service
- Detect repository root
- Get staged files list
- Generate unified diff for staged changes
- Parse repository metadata (name, branch, remote)
-
Build diff parsing service
- Parse unified diff format
- Extract file-level metadata (additions, deletions, renames)
- Structure diff data for frontend consumption
-
Create diff API endpoints
/api/diff/staged- returns parsed diff data/api/diff/files- returns file list with stats
Goal: Create, save, and manage reviews
-
Implement review service
- Create review from current staged changes
- Snapshot diff data (JSON serialization)
- Update review metadata and status
-
Build review API endpoints
- Full CRUD operations
- Pagination for list endpoint
- Status filtering
-
Add review val 8BD0 idation schemas
- Fastify JSON schema validation
- OpenAPI documentation generation
Goal: Basic diff viewing interface
-
Set up Vite + React project
- Configure Vite for library mode (embedding)
- Set up Tailwind CSS
- Create build pipeline for SPA embedding
-
Build layout components
- Header with navigation
- Sidebar with file tree
- Responsive layout
-
Implement diff visualization
- Integrate diff2html for rendering
- Configure Shiki for syntax highlighting
- Side-by-side and unified view modes
-
Create API client
- Typed fetch wrapper
- Error handling
- Loading states
Goal: Full commenting functionality
-
Implement comment service
- CRUD operations
- Resolve/unresolve functionality
- Code suggestion storage
-
Build comment API endpoints
- All CRUD endpoints
- Batch operations support
-
Create comment UI components
- Inline comment display
- Comment form with markdown support
- Code suggestion blocks
- Thread-style comment display
-
Add suggestion editor
- Monaco editor integration for code suggestions
- Diff preview for suggestions
Goal: Export functionality and UX improvements
-
Implement markdown export service
- Generate structured markdown report
- Include diff snippets with comments
- Summary statistics
-
Build export CLI command
- File output option
- Stdout support for piping
-
Add UI polish
- Keyboard shortcuts (j/k navigation, c for comment)
- File search/filter
- Comment count badges
- Status indicators
Goal: Comprehensive test coverage
-
Server tests (node:test)
- Service layer unit tests
- Repository tests with in-memory SQLite
- Route/API integration tests using Fastify's inject()
- Git operations with fixture repos
-
Frontend tests (Vitest)
- React component tests with Testing Library
- Hook tests
- Store tests
-
E2E tests (Playwright)
- Full review creation workflow
- Adding comments to diff lines
- Resolving/unresolving comments
- Export functionality
- Navigation and keyboard shortcuts
- Cross-browser testing (Chromium, Firefox, WebKit)
-
Documentation
- README with usage examples
- API documentation (auto-generated OpenAPI)
- Contributing guide
Goal: Responsive design and rich file viewing
-
Responsive sidebar
- Auto-collapse sidebar on mobile breakpoints (< 768px)
- Hamburger menu toggle for mobile
- Slide-out drawer animation
- Persist sidebar state preference
-
Full file view with commenting
- Add "View Full File" toggle in file header
- Fetch complete file content from git (not just diff hunks)
- Allow comments on any line, not just changed lines
- Visual distinction between changed and unchanged regions
- API endpoint:
GET /api/reviews/:id/files/:pathfor full file content
-
Image file support
- Detect image files by extension (.png, .jpg, .gif, .svg, .webp)
- Side-by-side image comparison for modified images
- Display added/deleted images appropriately
- Show image dimensions and file size
- Support for image diffing (optional: highlight changes)
-
Markdown file preview
- Detect markdown files (.md, .mdx)
- Toggle between raw diff and rendered preview
- Render markdown using a lightweight parser
- Support GitHub-flavored markdown (tables, task lists, code blocks)
- Comments visible in both raw and preview modes
Goal: Simplify review creation and support branch/commit reviews
-
Streamlined review creation
- Remove title and description fields from reviews (auto-generate title from first file or timestamp)
- When viewing staged changes, enable commenting immediately
- Auto-create review on first comment (lazy creation)
- If staged changes exist, always show them on homepage with "Start Review" prompt
- Single-click flow: view changes → comment → review is created
-
Review deletion from UI
- Add delete button to review list items
- Add delete confirmation modal
- Bulk delete option for multiple reviews
-
Branch comparison mode
- New "Compare Branches" option in UI
- Select source and target branches from dropdown
- API endpoint:
GET /api/diff/branches?from=<ref>&to=<ref> - Show diff between any two refs (branches, tags, commits)
- Create review from branch comparison
-
Commit range reviews
- "Select Commits" picker in UI
- Show recent commit history with checkboxes
- Select single commit or range of commits
- API endpoint:
GET /api/diff/commits?commits=<sha1>,<sha2>,... - API endpoint:
GET /api/git/commits?limit=20for commit history - Create review from selected commits
-
Database schema changes
- Remove
titleanddescriptioncolumns from reviews table - Add
source_typecolumn: 'staged' | 'branch' | 'commits' - Add
source_refcolumn for branch name or commit SHAs - Migration to handle existing data
- Remove
Goal: Add a todo list for tracking tasks during code review
-
Database schema for todos
- Create
todostable with id, content, completed, review_id (optional), created_at, updated_at - Todos can be global (repository-level) or linked to a specific review
- Index on review_id for fast filtering
- Create
-
Todo API endpoints
GET /api/todos- List all todos (with optional?review_id=<id>filter)POST /api/todos- Create a new todoPATCH /api/todos/:id- Update todo (content, completed status)DELETE /api/todos/:id- Delete a todoPOST /api/todos/:id/toggle- Toggle completed status
-
CLI commands for todo management
code-review todo add <content>- Add a new todocode-review todo list- List all todos (with--all,--done,--pendingfilters)code-review todo done <id>- Mark todo as completedcode-review todo undone <id>- Mark todo as not completedcode-review todo remove <id>- Delete a todocode-review todo clear --done- Remove all completed todos- Support
--jsonoutput for all list operations - Support
--review <id>to scope todos to a specific review
-
UI components
- Todo panel accessible from sidebar or header
- Slide-out drawer or modal for todo list
- Add todo inline input with enter to submit
- Checkbox to toggle completion
- Click to edit todo content
- Delete button with confirmation
- Filter tabs: All / Pending / Completed
- Optional: link todo to current review being viewed
- Drag-and-drop reordering (optional)
-
Integration with reviews
- Show todo count badge in UI
- Quick-add todo from comment (convert comment to todo)
- Filter todos by review when viewing a specific review
Reviews store a complete snapshot of the diff at creation time. This ensures:
- Reviews remain viewable even after changes are committed
- Historical record of what was reviewed
- No dependency on current git state after creation
The React frontend is bundled and embedded into the CLI package:
- Single
npm installfor everything - No separate frontend server in production
- Vite builds to
dist/web/, served by Fastify's static plugin - Development mode proxies API requests to backend
Suggestions are stored as markdown code blocks with metadata:
```suggestion
const result = items.filter(Boolean);
This allows:
- Easy rendering in the UI
- Clean markdown export
- Potential future "apply suggestion" functionality
### 4. Database Location
SQLite database is stored at:
- `<repository-root>/.code-review/reviews.db`
- Gitignored by default
- Portable with the repository if desired
### 5. Migration System
Version-based migrations using SQLite's `PRAGMA user_version`:
```typescript
interface Migration {
version: number;
name: string;
up: string; // SQL to apply
}
function migrate(db: DatabaseSync, migrations: Migration[]): void {
const currentVersion = getCurrentVersion(db); // PRAGMA user_version
const pending = migrations
.filter(m => m.version > currentVersion)
.sort((a, b) => a.version - b.version);
for (const migration of pending) {
db.exec('BEGIN TRANSACTION');
try {
db.exec(migration.up);
db.exec(`PRAGMA user_version = ${migration.version}`);
db.exec('COMMIT');
} catch (err) {
db.exec('ROLLBACK');
throw err;
}
}
}
Benefits:
- No external migration tool needed
- Atomic migrations with transaction rollback
- Version tracked in database itself
- Simple, auditable migration files
When --auth <token> flag is provided:
// Server-side: Fastify preHandler hook
fastify.addHook('preHandler', async (request, reply) => {
if (!config.authToken) return; // Auth disabled
const header = request.headers.authorization;
if (!header?.startsWith('Bearer ')) {
return reply.code(401).send({ error: 'Unauthorized' });
}
const token = header.slice(7);
if (token !== config.authToken) {
return reply.code(401).send({ error: 'Invalid token' });
}
});Client-side flow:
- Check
/api/healthfor auth requirement - If 401, prompt for token input
- Store token in localStorage
- Include
Authorization: Bearer <token>in all requests
{
"fastify": "^5.0.0",
"@fastify/static": "^8.0.0",
"@fastify/cors": "^10.0.0",
"@fastify/swagger": "^9.0.0",
"@fastify/swagger-ui": "^5.0.0",
"open": "^10.0.0",
"simple-git": "^3.25.0",
"diff": "^5.2.0",
"diff2html": "^3.4.0",
"shiki": "^1.0.0",
"uuid": "^10.0.0",
"zod": "^3.23.0"
}{
"react": "^18.3.0",
"react-dom": "^18.3.0",
"react-router-dom": "^6.26.0",
"zustand": "^5.0.0",
"@tanstack/react-query": "^5.50.0",
"clsx": "^2.1.0",
"tailwind-merge": "^2.4.0"
}{
"typescript": "^5.6.0",
"vite": "^6.0.0",
"@vitejs/plugin-react": "^4.3.0",
"vitest": "^2.0.0",
"@testing-library/react": "^16.0.0",
"@testing-library/user-event": "^14.5.0",
"jsdom": "^25.0.0",
"@playwright/test": "^1.49.0",
"tailwindcss": "^3.4.0",
"autoprefixer": "^10.4.0",
"postcss": "^8.4.0",
"@types/node": "^22.0.0",
"@types/react": "^18.3.0",
"@types/diff": "^5.2.0"
}{
"scripts": {
"dev": "vite",
"dev:server": "node --watch src/cli/index.ts serve",
"build": "vite build && tsc -p tsconfig.server.json",
"test": "npm run test:server && npm run test:web",
"test:server": "node --test tests/server/**/*.test.ts",
"test:web": "vitest run",
"test:watch": "vitest",
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:all": "npm run test && npm run test:e2e",
"lint": "eslint src tests"
}
}{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"skipLibCheck": true,
"paths": {
"@/server/*": ["./src/server/*"],
"@/web/*": ["./src/web/*"],
"@/shared/*": ["./src/shared/*"]
}
}
}export default defineConfig({
root: '.',
build: {
outDir: 'dist/web',
emptyDirOnly: true,
},
server: {
proxy: {
'/api': 'http://localhost:3847'
}
}
});import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests/e2e',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://localhost:3847',
trace: 'on-first-retry',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
webServer: {
command: 'npm run dev:server',
url: 'http://localhost:3847',
reuseExistingServer: !process.env.CI,
},
});- Functional: Can create reviews, add comments, and export to markdown
- Fast: Server starts in < 500ms, UI renders diff in < 100ms for typical files
- Reliable: No data loss, graceful error handling
- Maintainable: Clear separation of concerns, comprehensive types, good test coverage
- Portable: Single npm package, works on macOS/Linux/Windows
- AI-assisted review suggestions
- Team collaboration (multi-user)
- GitHub/GitLab integration for pushing reviews
- VS Code extension
- Apply suggestions directly to files
- Review templates
- Webhooks for CI integration