\n ![\"npm](\"https://img.shields.io/npm/v/glassbox.svg\")
\n ![\"Latest](\"https://img.shields.io/github/v/release/brianwestphal/glassbox?label=desktop%20app\")
![\"Node.js](\"https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg\"){kind=icon}
\n ![\"MIT](\"https://img.shields.io/npm/l/glassbox.svg\")
\n
\n\n**Glassbox** is a local, browser-based code review tool built for the AI coding workflow. You review the changes your AI made, annotate what's wrong (or right), and export structured feedback that AI tools can read and act on instantly.\n\nNo accounts. No pull requests. No waiting. Just you, the diff, and a tight feedback loop.\n\n
\n\n**Desktop app** (recommended) — download from [GitHub Releases](https://github.com/brianwestphal/glassbox/releases):\n\n| Platform | Download |\n|----------|----------|\n| macOS (Apple Silicon) | `.dmg` (arm64) |\n| macOS (Intel) | `.dmg` (x64) |\n| Linux | `.AppImage` / `.deb` |\n| Windows | `.msi` / `.exe` |\n\nAfter installing, open the app and click **Install CLI** to add the `glassbox` command to your PATH.\n\n**Or install via npm:**\n\n```bash\nnpm install -g glassbox\n```\n\nThen, from any git repository:\n\n```bash\nglassbox\n```\n\nThat's it. Data stays local. Works in any git repo.\n\n
\n\n
![\"Glassbox:](\"assets/demo.svg\")
\n\n![\"Inline](\"assets/demo-annotations.png\")
\n\n| Category | What it tells the AI |\n| --------------------- | ----------------------------------------------- |\n| **Bug** | \"This is broken. Fix it.\" |\n| **Fix needed** | \"This needs a specific change.\" |\n| **Style** | \"I prefer it done this way.\" |\n| **Pattern to follow** | \"This is good. Keep doing this.\" |\n| **Pattern to avoid** | \"This is an anti-pattern. Stop.\" |\n| **Note** | Context for the AI to consider. |\n| **Remember** | A rule to persist to the AI's long-term config. |\n\nAs you annotate, `.glassbox/latest-review.md` is updated automatically. You can tell your AI tool at any time:\n\n```\nRead .glassbox/latest-review.md and apply the feedback.\n```\n\nThe AI gets a structured file with every annotation, organized by file and line number, with clear instructions on how to interpret each category. It fixes the bugs, applies your style preferences, avoids the anti-patterns, and updates its own config with your \"remember\" items. You don't need to formally \"complete\" a review to share feedback — just annotate and switch to your AI tool.\n\nThen you run `glassbox` again. Your previous annotations carry forward — matched to the updated diff. Stale comments that no longer apply are flagged so you can keep or discard them. The loop continues until you're satisfied.\n\n---\n\n## How it works\n\n![\"Sequence](\"assets/sequence-diagram.svg\")
\n\n---\n\n## Features\n\n### Diffs & viewing\n\n- **Split and unified diffs** with syntax-colored add/remove/context lines\n- **Image and SVG diffs** — binary images and SVGs render in a **side-by-side** layout (with a left/right or over/under toggle), a **difference overlay**, a **swipeable slice tool**, single-side **A / B focus** modes, and pixel-precision synced zoom/pan. SVGs offer a *Code* / *Rendered* toggle so you can review either the source or the live-rendered output.\n- **Compare any two paths** — `glassbox --diff ![\"Image](\"assets/demo-image-comparison.png\")
\n\nAnd when \"correct\" means \"matches the design,\" **ground-truth comparison** (`glassbox --ground-truth ![\"Ground-truth](\"assets/demo-ground-truth.png\")
\n\n### Diagrams too, via content plugins\n\nReviewing a diagram's source text tells you what changed; seeing the diagram tells you what it _means_. **Content plugins** render specialized formats server-side — install one and a `.dot`, `.puml`, or `.mmd` file gets a **Code | Rendered** toggle: _Code_ is the ordinary text diff, _Rendered_ treats the diagram **like an image**, with the full image-review toolkit — side-by-side, difference overlay, slice, synced zoom.\n\n![\"A](\"assets/demo-plugin-rendered.png\")
\n\nThe same plugins render diagram-source **proof artifacts** attached to [AI review notes](#ai-review-notes) — so an AI's sequence-diagram evidence shows up as an actual diagram, inline with the diff:\n\n![\"A](\"assets/demo-plugin-mermaid-note.png\")
\n\nGraphviz ships built-in (WASM, no dependencies). PlantUML and Mermaid are one click away in **Settings → Plugins** (they use a local Java / headless-Chromium render, so they're opt-in), alongside an image-codecs plugin that adds WebP/AVIF support to ground-truth scoring. Everything stays local, and everything fails soft — without a plugin you simply see the source text. Want to render your own format? See the [plugin development guide](docs/plugin-development-guide.md).\n\n---\n\n## AI-Powered Review Intelligence\n\n> Entirely optional. Glassbox is fully functional without it.\n\nWhen reviewing a large diff, knowing _where to look first_ is half the battle. Glassbox can optionally connect to an AI provider to analyze your changes and surface what matters:\n\n### Risk Analysis\n\nEvery file is scored across six dimensions — security, correctness, error handling, maintainability, architecture, and performance — on a 0.0 to 1.0 scale. Files are ranked by their highest-risk dimension, so a single critical issue won't hide behind low averages.\n\nWhen you open a file, inline risk notes highlight the specific lines and concerns the AI flagged, giving you a heads-up before you even start reading.\n\n![\"Risk](\"assets/demo-risk-mode.png\")
\n\n### Narrative Reading Order\n\nFor large, multi-file changes, the AI determines the optimal reading order: types and interfaces first, then utilities, then business logic, then integration code. Each file gets walkthrough notes that explain what changed and how it connects to the rest of the diff — like having a colleague walk you through their PR.\n\n![\"Narrative](\"assets/demo-narrative-mode.png\")
\n\n### Guided Review\n\nIf you're learning a new language, onboarding to an unfamiliar codebase, or new to programming, Guided Review generates educational annotations inline with the diff. Enable it in Settings and select the topics that apply to you — \"Programming,\" \"This codebase,\" or specific languages. Glassbox runs a separate analysis pass and inserts green \"Learn\" notes that explain concepts, idioms, and design decisions relevant to your experience level.\n\nGuided Review works in all three sidebar modes (folder, risk, and narrative) and runs independently of risk or narrative analysis. When enabled, risk and narrative analysis also adjust their output to be more detailed and educational.\n\n![\"Guided](\"assets/demo-guided-review.png\")
\n\n### How to use it\n\nClick the shield or book icon in the sidebar to switch from the default folder view to risk or narrative mode. If you haven't configured an API key yet, a settings dialog will prompt you. Analysis runs once and results are cached for the session. To enable Guided Review, open the Settings dialog (gear icon) and check \"Enable guided review.\"\n\n![\"Settings](\"assets/demo-settings.png\")
\n\n### Supported providers\n\n| Provider | Models | Runs |\n| ------------- | -------------------------------------------- | ----------------------------- |\n| **Anthropic** | Claude Sonnet 4.6, Opus 4.8, Haiku 4.5 | Cloud — `ANTHROPIC_API_KEY` |\n| **OpenAI** | GPT-4o, GPT-4o Mini | Cloud — `OPENAI_API_KEY` |\n| **Google** | Gemini 2.5 Flash, Gemini 2.5 Pro | Cloud — `GEMINI_API_KEY` |\n| **Local** | Any Ollama / LM Studio model | On your machine — no key |\n| **Apple** | On-device Apple Intelligence | On-device (macOS) — no key |\n\nAvailable models are discovered live from each provider, so the list stays current without an app update. Switch providers and models in the settings dialog (gear icon in the sidebar).\n\n**Local and on-device models are free, private, and offline.** Point Glassbox at any OpenAI-compatible server like [Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/), or — on a Mac with Apple Intelligence — run analysis on-device with Apple Foundation Models. Either way, no API key is required and your code never leaves your machine.\n\n### API key storage\n\nYour API key never leaves your machine. Glassbox resolves keys in this order:\n\n1. **Environment variables** — if `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` is set, it's used automatically. Nothing is stored.\n2. **OS keychain** — on macOS (Keychain), Linux (GNOME Keyring / KDE Wallet via `secret-tool`), or Windows (Credential Manager). Keys are encrypted by your operating system and tied to your user account.\n3. **Config file** — stored in `~/.glassbox/config.json` with `0600` permissions, base64-encoded. Use this as a fallback if your OS keychain isn't available.\n\nKeys entered through the settings dialog are stored in the OS keychain by default when available, and never sent anywhere except directly to the AI provider's API.\n\n---\n\n## AI Review Notes\n\nWhen an AI writes or modifies code, it knows _why_ each non-obvious change is the way it is and _what proves it correct_ — and then throws that context away. The reasoning lives in the model's head at edit time, and the reviewer is left to reconstruct it from prose in a ticket or commit message.\n\n**AI Review Notes** give the generating AI a structured, line-anchored channel to record that reasoning. The AI emits notes with the `glassbox note` command; they're stored as committed SARIF under `.pr-notes/` — tool-neutral and travelling with the repo — and Glassbox renders them review-comment-style at the exact line they apply to:\n\n- **Rationale** — why this change, and what alternatives were rejected\n- **Proof** — the test that passed, a measurement, or a before/after screenshot (notes can carry text, image, and diagram-source artifacts — diagrams render inline via [content plugins](#diagrams-too-via-content-plugins))\n- **Risk / assumption** — what a reviewer should double-check\n\n![\"AI-authored](\"assets/demo-review-notes.png\")
\n\nYou can **reply** to any note with your own annotation — threaded beneath it like a pull-request comment. When a note's code later changes, Glassbox re-anchors it to its new line and flags it **outdated**, so stale reasoning never misleads you. And because the notes are plain SARIF in `.pr-notes/`, any tool or teammate can read them — Glassbox is just the most pleasant way to consume them.\n\nSee [docs/20-ai-review-notes.md](docs/20-ai-review-notes.md) for the format and the producer-side `glassbox note` CLI.\n\n---\n\n## For AI tools: integrating with Glassbox\n\nIf you're an AI coding tool or agent working in a project that uses Glassbox, **[docs/ai-integration.md](docs/ai-integration.md)** is the integration hub — how to launch a review, record line-anchored rationale/proof (`glassbox note`), export ground-truth image proof, consume the exported feedback (`.glassbox/latest-review.md`), and respond to the MCP/Claude channel. The repo's [AGENTS.md](AGENTS.md) is a one-screen router to it (and, separately, to the contributor docs for agents hacking on Glassbox itself).\n\n---\n\n## Install\n\n### Desktop app (recommended)\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/brianwestphal/glassbox/releases).\n\nOn first launch, the app will prompt you to install the `glassbox` CLI command. This creates a symlink so you can launch the desktop app from any project directory. You can also install it manually:\n\n**macOS:**\n```bash\nsudo sh -c 'mkdir -p /usr/local/bin && ln -sf \"/Applications/Glassbox.app/Contents/Resources/resources/glassbox\" /usr/local/bin/glassbox'\n```\n\n**Linux:**\n```bash\nln -sf /path/to/glassbox/resources/glassbox-linux ~/.local/bin/glassbox\n```\n\nThe desktop app includes automatic updates — new versions are downloaded and applied in the background.\n\n### npm\n\nAlternatively, install via npm (runs in your browser instead of a native window):\n\n```bash\nnpm install -g glassbox\n```\n\nRequires **Node.js 20+** and **git**.\n\n---\n\n## Usage\n\nRun from inside any git repository:\n\n```bash\n# Review uncommitted changes (default, same as no arguments)\nglassbox\n\n# Review only staged changes\nglassbox --staged\n\n# Review a specific commit\nglassbox --commit abc123\n\n# Review current branch vs main\nglassbox --branch main\n\n# Review a range of commits\nglassbox --range main..feature-branch\n\n# Review specific files\nglassbox --files \"src/**/*.ts,lib/*.js\"\n\n# Review entire codebase\nglassbox --all\n\n# Compare two arbitrary files or folders by path (no git repo required)\nglassbox --diff ./dist-old ./dist-new\n\n# Compare actual images against expected/ground-truth images (no git repo required)\nglassbox --ground-truth ./screenshots/manifest.json\n\n# Resume a previous review\nglassbox --resume\n```\n\n### All options\n\n| Flag | Description |\n| ---------------------- | -------------------------------------------------- |\n| _(no flag)_ | Same as `--uncommitted` |\n| `--uncommitted` | Staged + unstaged + untracked changes |\n| `--staged` | Only staged changes |\n| `--unstaged` | Only unstaged changes |\n| `--commit