# Loupe

> Pin feedback to the live UI. Hand it to Claude.

Loupe lets product managers inspect any element on a running product, pin a comment to
it, and capture a screenshot — then hand that feedback straight to Claude Code as an
actionable, fully-contextualized backlog. Comments persist and re-anchor across
redeploys.

📖 **[Read the full documentation →](https://mohamed-ashraf-elsaed.github.io/loupe/guide/)**

This is a monorepo (npm workspaces). Every piece runs locally with **no external
services** — the database is embedded Postgres (PGlite), so `npm install && npm run
build && npm run seed && npm start` is the whole setup.

## Packages

```
packages/
  shared/      canonical types + normalizeUrl() (built to dist, consumed by all)
  sdk/         embeddable browser SDK — inspect, comment (element / region / free note), capture, re-anchor; dockable control panel
    demo/      a fake product ("Acme Analytics") to try it on
  server/      comment API — node:http, Postgres, object storage, HMAC auth, static hosting
  dashboard/   Kanban triage board (reads the API)
  mcp/         MCP server — exposes comments to Claude Code
  extension/   MV3 browser extension — inspect/comment on ANY site, pixel-perfect capture
  laravel/     Loupe for Laravel — composer package: widget + your DB + gating + dashboard + MCP
  hub/         Loupe Hub (optional, private) — orgs/members/projects; verifies issues, forwards to webhooks
```

### Loupe for Laravel

Prefer to run the whole loop inside your own app? [`loupekit/laravel`](packages/laravel)
is a Composer package that embeds the widget, stores comments in **your** database, gates
access with **your** authorization rules, serves the dashboard on **your** routes, and
exposes the backlog to Claude over MCP — no separate Node backend. See the
[full guide](docs/LARAVEL.md).

```bash
composer require loupekit/laravel
php artisan loupe:install && php artisan migrate
# add @loupeWidget to your layout, then open /loupe/dashboard
```

Optional: set `LOUPE_HUB_URL`, `LOUPE_PROJECT_ID` and `LOUPE_PROJECT_SECRET` to also send
every new comment to [Loupe Hub](packages/hub), which checks the author belongs to your
organization and forwards it to your project's webhook.

## Run it

```bash
npm install
npm run build          # shared → sdk → dashboard → extension
npm run seed           # creates the demo project; prints its admin key + demo HMAC
npm start              # one process on http://localhost:8787 serves API + dashboard + demo + SDK
```

Then open:

- **Demo product** — http://localhost:8787/demo/ (leave feedback; persists to the API)
- **Triage board** — http://localhost:8787/dashboard/?key=<admin key from `npm run seed`>

Point **Claude Code** at the comments:

```json
{
  "mcpServers": {
    "loupe": {
      "command": "node",
      "args": ["/absolute/path/to/loupe/packages/mcp/index.ts"],
      "env": {
        "LOUPE_API": "http://localhost:8787",
        "LOUPE_PROJECT_KEY": "pk_demo_acme",
        "LOUPE_ADMIN_KEY": "<admin key from npm run seed>"
      }
    }
  }
}
```

Then: *"list the open Loupe comments and work through them."* Claude calls
`list_comments` → `get_comment` (request + element HTML + computed styles + the
**screenshot as an image** + any screen-recording URL) → rewrites the UI →
`propose_change` (its **modified HTML/CSS**, which the dashboard renders as code + a live
before/after preview for the dev team) → `update_status`.

## Architecture notes

**Database** — `server/db.ts` is a one-function `query()` seam. With `DATABASE_URL` set
it uses node-postgres against real/hosted Postgres; otherwise embedded PGlite on disk.
Same SQL, same `$1` params.

**Auth** — every project has a `secret`. Writes require `X-Loupe-User` +
`X-Loupe-Hmac` = HMAC-SHA256(userId, secret) (the host app's server computes this and
injects it — the demo's value is precomputed by `npm run seed`). The dashboard and MCP
server authenticate as admin with `X-Loupe-Admin` = secret. Screenshot blobs are served
by unguessable id (prod: signed URLs).

**Object storage** — `server/blobs.ts` is the seam (local disk now, S3 later). The SDK
uploads a screenshot to `POST /v1/blobs` and stores only the returned **URL** on the
comment, so lists/reads stay small.

**URL normalization** — `normalizeUrl()` in `@loupekit/shared` strips `utm_*`, click ids,
and Loupe's dev params, so a comment on `/checkout?utm_source=x` and one on `/checkout`
don't fragment. Applied server-side on write and query.

## Browser extension

The extension reuses the exact SDK core; its only difference is the screenshot source —
`chrome.tabs.captureVisibleTab` (real pixels), cropped to the element with redaction,
wired via the SDK's `captureScreenshot` override. Load it manually:

```bash
npm run build:extension      # builds packages/extension/content.js
```

1. `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select
   `packages/extension`.
2. Click the Loupe icon → set project key (`pk_demo_acme`), user, API base
   (`http://localhost:8787`), and (optionally) the demo HMAC → **Start Loupe on this tab**.

> Note: the extension is validated by build + manifest/bundle checks; full in-browser E2E
> wasn't automated in this repo's headless setup.

## Roadmap

1. **Client SDK** ✓ — inspect, comment, capture, re-anchor across redeploys.
2. **Backend API** ✓ — Postgres, HMAC auth + per-project secrets, object storage, static hosting.
3. **MCP server** ✓ — comments as a Claude Code backlog.
4. **Dashboard** ✓ — Kanban triage.
5. **Hardening** ✓ — monorepo, Postgres, enforced auth, blob storage, URL normalization.
6. **Browser extension** ✓ — pixel-perfect capture on any site.

**Next:** real cloud object storage (S3/R2) + signed URLs, project/team management UI,
Postgres migrations tooling, and packaging the SDK/MCP to npm + the extension to the
Chrome Web Store.

## Author

**Loupe is created and maintained by [Mohamed Ashraf Elsaed](https://www.linkedin.com/in/mohamedashrafelsaed/).**

- 💼 LinkedIn: [mohamedashrafelsaed](https://www.linkedin.com/in/mohamedashrafelsaed/)
- 🐙 GitHub: [@mohamed-ashraf-elsaed](https://github.com/mohamed-ashraf-elsaed)
- ✉️ Email: [m.ashraf.saed@gmail.com](mailto:m.ashraf.saed@gmail.com)

If Loupe is useful to you, a ⭐ on the repo and a connection on LinkedIn are always
appreciated. For consulting or collaboration, reach out via any of the links above.

## License

MIT © [Mohamed Ashraf Elsaed](https://www.linkedin.com/in/mohamedashrafelsaed/)