loupe

Loupe

Loupe is an open-source visual feedback tool. You pin comments to elements of a live web page, and an AI agent such as Claude Code picks them up over MCP (Model Context Protocol, the standard that lets an agent call external tools).

Contents

• What you can do
• Choose how to install
• Try it in five minutes
• Packages
• Documentation
• Contributing
• Author
• License

What you can do

• Pin feedback where it belongs. Comment on a single element, drag a region, or leave a free note on the page. Pins re-anchor after a redeploy: Loupe finds the same element again, even when its markup changes.
• Capture what you see. Attach a screenshot or a short screen recording of a region. Elements marked with data-loupe-redact are left out of every screenshot. Screen recordings capture the real pixels, redacted elements included.
• Discuss in threads. Reply under each comment, @mention teammates, and react with 👍 🎉 👀 🙏 ❤️ 🚀.
• Triage on a five-stage board. Move comments through Queue, To Do, In Progress, In Review and Resolved.
• Hand the backlog to an agent. The @loupekit/mcp server gives Claude Code 19 tools, including list_comments, get_comment, propose_change and update_status. The Laravel package ships its own MCP server with those 4 core tools when the optional laravel/mcp package is installed (php artisan mcp:start loupe).
• Run it inside Laravel. The loupekit/laravel package stores comments in your database, uses your authentication and gates, and serves the board on your routes.
• Route tickets between apps. Loupe Hub, a separate server you host, sends a comment from one project to another in the same organization (a group of projects in Hub), and syncs status changes and replies both ways.

Choose how to install

Integration	Use it when	Guide
Script tag	You want the widget on any page without a build step.	Embed Loupe with a script tag
npm package	Your app uses a bundler: React, Vue, or any single-page app.	Install Loupe from npm
Laravel	Your app is built on Laravel 11, 12 or 13.	Install Loupe in a Laravel app
Browser extension	You want to comment on a site you cannot change.	Use the browser extension
MCP clients	You want Claude Code, or another MCP client, to work through the comments.	Connect MCP clients
Local server and dashboard	You want the Node API and the Kanban board (columns that comment cards move across) on your machine.	Run the local server
Loupe Hub	You want to route tickets between several apps.	Self-host Loupe Hub

Try it in five minutes

This quick start runs the local server, leaves one comment on the demo page, and shows it on the board.

Prerequisites

• Node 24. The local server runs its TypeScript files directly with node index.ts, which needs Node 24. Run node --version. You should see v24 followed by a minor version.
• npm, which comes with Node.
• git, to clone the repository.

Steps

1. Clone the repository and move into it:

   git clone https://github.com/mohamed-ashraf-elsaed/loupe.git
   cd loupe
   

   Run every later command from this folder.

2. Install the workspace dependencies:

   npm install
   

   You should see npm finish with an added ... packages summary.

3. Build the packages:

   npm run build
   

   You should see the command finish with no line that starts with npm error.

4. Create the demo project:

   npm run seed
   

   You should see Seeded project: pk_demo_acme, followed by an admin key line. The admin key is the project secret. The dashboard asks for it in its address. Its default value is sk_demo_acme_0f3b9c.

5. Start the server:

   npm start
   

   You should see:

   [loupe] API + static on http://localhost:8787  (dashboard: /dashboard/ · demo: /demo/)
   

   Leave this terminal running.

6. In your browser, open http://localhost:8787/demo/.

   You should see the Q3 Performance Overview page with the Loupe panel open on the right and a short tour. Click Next through the tour, then click Done.

7. Leave a comment:

   1. In the panel, on the Home tab, click ✛ Pin feedback on this page.
   2. Click the Send invite button in the invite form.
   3. Type a title and a description, then click Comment.

   You should see a numbered pin, 1, on the Send invite button.

8. In a new browser tab, open the board:

   http://localhost:8787/dashboard/?key=<ADMIN_KEY>
   

   Replace <ADMIN_KEY> with the admin key that npm run seed printed in step 4.

   You should see the board with five columns: Queue, To Do, In Progress, In Review and Resolved. Your comment is a card in the Queue column.

Troubleshooting

Symptom	Cause	Fix
npm start fails, or the server does not start on port 8787.	Another program is using port 8787.	Stop the other program, or start on another port with PORT=9000 npm start.
npm start fails on node index.ts.	Your Node version is older than 24.	Install Node 24, check it with node --version, then run npm start again.
Clicking Comment on the demo page fails.	You ran npm run seed with LOUPE_DEMO_SECRET set. The demo page signs requests with the default secret.	Unset LOUPE_DEMO_SECRET, run npm run seed again, then reload the demo page.
The board is empty.	You have not left a comment yet.	Do step 7, then reload the board.

Next steps

• Follow the full walkthrough, which also connects Claude Code: Leave your first comment locally.
• Add Loupe to your own app with one of the guides in Choose how to install.

Packages

Package	Registry	What it is
@loupekit/sdk	npm	The embeddable widget: inspect, comment, capture, re-anchor.
@loupekit/shared	npm	Shared types, board stages and helpers used by every package.
@loupekit/mcp	npm (bin loupe-mcp)	The MCP server over stdio (standard input and output, which Claude Code uses to start and talk to a local server), plus a local bridge on 127.0.0.1: a small HTTP server that lets the widget reach the agent, for example in its Chat tab.
loupekit/laravel	Packagist	The Laravel package. Mirrored from packages/laravel to loupe-laravel.
Extension	Not published; load unpacked (see the guide)	The Manifest V3 browser extension. A private workspace.
Server	Not published; run from this repo	The Node API that also serves the dashboard and the demo.
Dashboard	Not published; run from this repo	The Kanban triage board.
Hub	Not published; run from this repo	Loupe Hub: organizations, projects and ticket routing. See How Loupe Hub works.

Documentation

• Documentation index
• The Loupe guide
• The Loupe wiki
• Changelog

Contributing

• Contributing to Loupe
• Testing
• Releasing

Author

Loupe is created and maintained by Mohamed Ashraf Elsaed.

• 💼 LinkedIn: mohamedashrafelsaed
• 🐙 GitHub: @mohamed-ashraf-elsaed
• ✉️ Email: m.ashraf.saed@gmail.com

License

MIT © Mohamed Ashraf Elsaed. See LICENSE.