\n\n# Lazy Review — PR Review Assistant\n\nA CLI tool that reviews GitHub pull requests using local AI models. Point it at a repository, select a PR, and it posts a structured review comment back to GitHub — no cloud inference, no API keys beyond GitHub OAuth.\n\n## Installation\n\nLazy Review relies on several native C++ modules (like `better-sqlite3` and `tree-sitter`) for fast local vector search and code parsing. Because of this, **we strongly recommend using `npm`** for the global installation.\n\n```bash\nnpm install -g @djibrilm/lazy-review\nlrv run\n```\n\nThis will start the local server on `http://localhost:16500`.\n\n### Troubleshooting Installation Errors\n\nIf you encounter an error like `Error: Could not locate the bindings file`, it means the native dependencies failed to compile or download during installation.\n\n**1. Using `pnpm` or `yarn`**\nThese block build scripts by default, preventing C++ binaries from downloading.\n\n- **For pnpm:** Run `pnpm approve-builds -g`. Use the `Space` bar to select the blocked packages, then press `Enter`.\n- **For yarn:** Add `enableScripts: true` to your `.yarnrc.yml` before installing.\n _(Alternatively, just install via `npm` instead)._\n\n**2. Missing Build Tools**\nIf you are on a very new or uncommon version of Node.js (e.g. Node 26), prebuilt binaries may not exist yet, forcing the modules to compile from source. If this fails, ensure you have C++ build tools installed:\n\n- **macOS:** Run `xcode-select --install`\n- **Linux:** Run `sudo apt-get install build-essential python3`\n- **Windows:** Run `npm install --global windows-build-tools`\n\n**3. EPERM: operation not permitted (macOS/Linux)**\nIf you are installing globally using `sudo npm install -g @djibrilm/lazy-review` and see a `Download failed: EPERM` error, `npm` has downgraded permissions during the post-install step. To fix this, tell `npm` to keep root permissions during the installation scripts:\n\n```bash\nsudo npm install -g @djibrilm/lazy-review --unsafe-perm\n```\n\n### From source\n\nRequires Node.js 18+ and pnpm.\n\n```bash\ngit clone https://github.com/djibrilm/lazy-review\ncd lazy-review\npnpm install\npnpm run dev\n```\n\nThis starts both the Express server (port `16500`) and the Vite dev server concurrently.\n\n## Overview\n\nLazy Review fetches PR diffs from GitHub and runs them through a multi-agent pipeline on your machine. The output is a structured GitHub PR review comment with categorized findings (`approve` / `request_changes` / `comment`), severity scores, and file-level annotations.\n\nIt uses two models:\n\n- A coding LLM (~5 GB RAM) for review generation\n- An embedding model (~2 GB RAM) for semantic codebase search\n\nBoth are downloaded and managed via the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk).\n\n## Review pipeline\n\nA review goes through five sequential stages:\n\n1. **Change Analyzer** — classifies the PR diff and selects which specialist reviewers are needed (e.g. `security`, `performance`, `concurrency`, `correctness`, `architecture`, `maintainability`)\n2. **Specialist Reviewers** — each runs a ReAct loop, forming hypotheses and querying the Repository Explorer for evidence rather than reading files directly\n3. **Repository Explorer** — a sub-agent with deterministic tools (`read_file`, `search_symbol`, `semantic_search`) that answers evidence queries from the Specialist Reviewers\n4. **Finding Verifier** — receives each candidate finding and attempts to disprove it by searching for cleanup handlers, timeouts, or lifecycle methods that would make the issue a false positive\n5. **Secret Scanner** — independently scans diff file names for sensitive candidates (`.env`, private keys, credential bundles), reads the actual diff content to confirm before reporting\n\nConfirmed findings are deduplicated by a hash of their text and location, ranked by `Impact × Likelihood`, and included in the final review verdict (`approve` / `request_changes` / `comment`).\n\n## Codebase indexing\n\nWhen you add a repository, Lazy Review scans the source tree and builds a local vector index. It:\n\n- Parses symbols from TypeScript, JavaScript, Python, Rust, and Go files using Tree-sitter\n- Chunks content at safe token boundaries (the embedding model has a 512-token context window)\n- Stores embeddings in SQLite using the `sqlite-vec` extension\n\nThe index is used during reviews to provide semantic context to the agents.\n\n## Tool-call parsing\n\nLocal models don't always return well-structured tool calls. The agent loop handles two fallback cases:\n\n- A regex parser for non-standard formats (e.g. the `<|tool_call|>` dialect used by some quantized models)\n- Tool results from fallback-parsed calls are injected as `user` messages to avoid strict API validation errors\n\n## Tech stack\n\n| Layer | Tech |\n| ----------- | --------------------------------------------- |\n| Backend | Node.js, Express 5, TypeScript |\n| AI | QVAC SDK, LangChain |\n| Database | SQLite (TypeORM + better-sqlite3), sqlite-vec |\n| AST Parsing | Tree-sitter (TS, JS, Python, Rust, Go) |\n| Real-time | socket.io |\n| Frontend | React, Vite, TanStack Query |\n| CLI | Commander.js |\n\n## Hardware requirements\n\nTested on a Mac Mini (Apple Silicon). You need ~7 GB of free RAM to hold both models simultaneously:\n\n| Model | RAM |\n| --------------- | ----- |\n| Coding LLM | ~5 GB |\n| Embedding Model | ~2 GB |\n\nSince the models alone take up around 7 GB and other computer operations also need space, a good environment should have around 12 GB to 16 GB of total RAM.\n\nGPU inference can be toggled in Settings. If the app crashes during model initialization (common on older GPUs), switch to CPU inference.\n\n## CLI Commands\n\nThe CLI is available as either `lazy-review` or the `lrv` shorthand.\n\n### `run`\n\nStarts the Lazy Review server.\n\n```bash\nlrv run\n```\n\n## Setup\n\n1. Open Settings → Local AI Models and download both models.\n2. Open Settings → GitHub Authentication and connect your GitHub account.\n3. Add a repository from the dashboard. Lazy Review will clone it and index the codebase.\n4. Select a PR from the repository view and run a review.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"Lazy](\"frontend/public/resources/images/logo.png\"){kind=logo}
![\"Lazy](\"./logo.png\"){kind=logo}
![\"Lazy](\"https://github.com/DjibrilM/lazy-review/raw/develop/frontend/public/resources/images/logo.png\"){kind=logo}