Skip to content
Back to search

uisight

Your AI can already see the screen — it just can't measure it. Live mobile+desktop sessions, a measurement engine (contrast, touch targets, theme drift) reporting findings as text, and a panel you and your agent share. MCP server for web/responsive UIs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sololabstr--uisight/badge.svg)](/listings/sololabstr--uisight)

HTML

<a href="/listings/sololabstr--uisight"><img src="/api/listings/sololabstr--uisight/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# one-shot audit: PNGs + gallery + report for iPhone/Pixel/desktop, light+dark
npx uisight https://yourapp.com --theme both

# live panel: mobile + desktop side by side, you browse, AI watches (and vice versa)
npx -y -p uisight uisight-panel http://localhost:3000

**First run.** Playwright ships its driver over npm but downloads browsers separately, so the first run has nothing to drive. In a terminal, uisight offers to fetch what it needs (Chromium is about 700 MB on disk, once) and shows the download. Where there is nobody to answer — CI, or a panel an editor or agent host started — it never asks and never downloads; it names the exact command instead. `UISIGHT_NO_INSTALL=1` turns the offer off everywhere, and you can always do it yourself:

npx playwright install chromium        # add webkit for the real iOS Safari engine

The one-shot audit produces a device × theme gallery with findings per card:

Hook it into your AI (MCP)

# Claude Code
claude mcp add --scope user uisight -- npx -y -p uisight@latest uisight-mcp

For Cursor / Antigravity / other MCP hosts, add to your MCP config:

{ "mcpServers": { "uisight": { "command": "npx", "args": ["-y", "-p", "uisight@latest", "uisight-mcp"] } } }

Then just tell your agent: *"look at my app with uisight"*. The panel server starts automatically when needed.

Claude Desktop (one click)

Download `uisight-<version>.mcpb` from the [latest release](https://github.com/sololabstr/uisight/releases/latest) and open it. Claude Desktop installs it and asks three things: the page to open, the tool set (`all` or `core`), and whether to download the browser on first use. There is no JSON to edit.

The bundle carries the server and its dependencies (about 7 MB). Browsers are not in it, which is what that third question is about: leave it on and a missing Chromium is fetched once, on the first tool call, by the Playwright version the bundle was built with. Build the bundle yourself with `node scripts/build-mcpb.mjs`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 326 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # uisight
  2. [![CI](https://github.com/sololabstr/uisight/actions/workflows/ci.yml/badge.svg)](https://github.com/sololabstr/uisight/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/uisight)](https://www.npmjs.com/package/uisight)
  4. **Your AI can already see the screen. It just can't measure it.**
  5. Screenshots make an agent *guess*: "that heading looks a bit faint." uisight makes it **know**:
  6. ```diff
  7. - from a screenshot: "the heading looks a little washed out, maybe adjust the color?"
  8. + from uisight: INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline"
  9. + (text rgba(255,255,255,.5) / bg rgb(247,247,248))
  10. ```
  11. One is an impression. The other is a measurement with a selector attached — the agent fixes *that* element instead of hunting for it.
  12. uisight is an [MCP](https://modelcontextprotocol.io) server for **web and responsive UIs** (Claude Code, Cursor, Antigravity, anything that speaks MCP). It runs live mobile + desktop sessions side by side, measures what it finds, and puts you and the agent in front of the exact same screen.
  13. Built by a solo founder who got tired of taking phone screenshots, pasting them into chat, and typing "the button looks broken, can you see it?"
  14. ![uisight live panel — desktop and mobile side by side, with per-device inspection findings](docs/assets/live-panel.png)
  15. *The live panel: desktop + mobile sessions of the same site, URL-synced. Inspect runs on every screen; findings come back per device. Your AI sees this exact view through MCP.*
  16. ## What makes it different
  17. | | Multi-viewport browsers<br>(Polypane etc.) | Browser tools / computer use<br>(Playwright MCP, agent harnesses) | Native app toolkits<br>(Argent etc.) | **uisight** |
  18. |---|---|---|---|---|
  19. | Measures the UI (`1.14:1`, not "looks low") | ✅ for humans | — | — | ✅ **as text, for the agent** |
  20. | Human + agent share one live session | — | — | — | ✅ |
  21. | Device × theme matrix in one run | ✅ | — | — | ✅ |
  22. | Human pins a bug → agent reads note + frame | — | — | — | ✅ |
  23. | Native iOS/Android apps | — | — | ✅ | — (web only) |
  24. The measurement engine is the heart: instead of your AI burning tokens squinting at screenshots, `inspect` returns findings like
  25. ```
  26. [mobile · Pixel 7 · light] https://yourapp.com/
  27. INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline" (text rgba(255,255,255,.5) / bg rgb(247,247,248))
  28. BUTTON a.text-white "Get Started" → text/background contrast 3.35:1
  29. touch target below 44px 180x23 — "read the guide"
  30. ```
  31. Text findings are cheap, precise, and directly actionable — your AI fixes the exact selector instead of guessing.
  32. ## "My agent already does this"
  33. Fair — and partly true. Computer use, browser tools and most agent harnesses can already open a page and take a screenshot. That's the part uisight doesn't try to replace. Three things are still missing:
  34. **1. Looking isn't measuring.** A vision model reading a screenshot cannot tell you a contrast ratio. It can't tell 4.6:1 (fine) from 4.3:1 (fails WCAG AA) — they look identical. It won't notice that a tap target is 41px instead of 44px, or that an element renders identically in light and dark mode because its color is hard-coded. uisight computes these from the live DOM: alpha-composited backgrounds, gradient text, `oklch()` colors and all.
  35. **2. The same price buys far more.** This used to claim a screenshot costs several times what a measurement does. Measured, that is not true: a mobile frame is ~460 tokens and the matching `inspect` result is ~570. `inspect` is not the cheap option — it is the option that says `4.38:1 (threshold 4.5)` where a picture only lets the model guess.
  36. The real saving is a different choice: `uisight <url>` writes a report the model reads once (~800 tokens), while driving the MCP tools screen by screen re-sends the whole conversation at every step. Someone put the problem perfectly under the launch thread: *"it burns some tokens but it manages."* [What it costs](#what-it-costs) has the whole table, because a claim like this one is worth checking.
  37. **3. Nobody's watching with you.** In the usual setup the agent looks at the page alone and reports back. Here you both watch the same live session — you see what it does as it does it, and when *you* spot something, you pin it (📌) with a note and the agent reads your note plus that exact frame. No more describing a bug in words.
  38. Scope note: uisight is for **web and responsive UIs**. For native iOS/Android app control, [Argent](https://github.com/software-mansion/argent) is excellent and does far more than we do there.
  39. ## Quickstart
  40. ```bash
  41. # one-shot audit: PNGs + gallery + report for iPhone/Pixel/desktop, light+dark
  42. npx uisight https://yourapp.com --theme both
  43. # live panel: mobile + desktop side by side, you browse, AI watches (and vice versa)
  44. npx -y -p uisight uisight-panel http://localhost:3000
  45. ```
  46. **First run.** Playwright ships its driver over npm but downloads browsers
  47. separately, so the first run has nothing to drive. In a terminal, uisight offers
  48. to fetch what it needs (Chromium is about 700 MB on disk, once) and shows the download. Where there is
  49. nobody to answer — CI, or a panel an editor or agent host started — it never
  50. asks and never downloads; it names the exact command instead. `UISIGHT_NO_INSTALL=1`
  51. turns the offer off everywhere, and you can always do it yourself:
  52. ```bash
  53. npx playwright install chromium # add webkit for the real iOS Safari engine
  54. ```
  55. The one-shot audit produces a device × theme gallery with findings per card:
  56. ![uisight gallery — 4 devices × light/dark with findings per card](docs/assets/gallery.png)
  57. ### Hook it into your AI (MCP)
  58. ```bash
  59. # Claude Code
  60. claude mcp add --scope user uisight -- npx -y -p uisight@latest uisight-mcp
  61. ```
  62. For Cursor / Antigravity / other MCP hosts, add to your MCP config:
  63. ```json
  64. { "mcpServers": { "uisight": { "command": "npx", "args": ["-y", "-p", "uisight@latest", "uisight-mcp"] } } }
  65. ```
  66. Then just tell your agent: *"look at my app with uisight"*. The panel server starts automatically when needed.
  67. ### Claude Desktop (one click)
  68. Download `uisight-<version>.mcpb` from the [latest release](https://github.com/sololabstr/uisight/releases/latest)
  69. and open it. Claude Desktop installs it and asks three things: the page to open,
  70. the tool set (`all` or `core`), and whether to download the browser on first use.
  71. There is no JSON to edit.
  72. The bundle carries the server and its dependencies (about 7 MB). Browsers are not
  73. in it, which is what that third question is about: leave it on and a missing
  74. Chromium is fetched once, on the first tool call, by the Playwright version the
  75. bundle was built with. Build the bundle yourself with `node scripts/build-mcpb.mjs`.
  76. ## MCP tools
  77. | Tool | What it does |
  78. |---|---|
  79. | `see_screen` | Returns the current screen as an image — the exact frame the human sees in the panel |
  80. | `inspect` | Runs contrast / touch-target / overflow / theme checks; returns **measured findings as text** |
  81. | `goto` | Navigates all sessions to a URL (localhost included) |
  82. | `tap` / `type_text` / `scroll` | Drives the page — the human watches it happen live |
  83. | `set_device` | Switches device profile (iphone-15, iphone-se, pixel, galaxy, ipad, desktop, laptop) or light/dark theme |
  84. | `status` | Open URL, sessions, recent console/network errors — first stop when hunting a bug |
  85. | `marks` | Reads the notes the human pinned in the panel (📌 note + screenshot at that moment) |
  86. Turkish tool names available with `UISIGHT_LANG=tr` (`ekrani_gor`, `denetle`, ...).
  87. ## The panel (human side)
  88. `npx -y -p uisight uisight-panel <url>` opens a browser page at `localhost:5055`:
  89. - **Mobile + desktop side by side**, both live, URL-synced
  90. - Click = tap on that device · wheel = scroll · type after clicking
  91. - Per-pane device switcher, shared light/dark toggle
  92. - **Inspect** button runs the measurement engine on every screen
  93. - **📌 Pin**: type a note, pin it — your AI reads note + screenshot via `marks`. No more "let me describe what I'm seeing."
  94. Works inside VS Code / Antigravity via *Simple Browser: Show* → `http://localhost:5055`.
  95. ## What it checks
  96. **Can you read it**
  97. - Invisible text (contrast < 1.6:1) and WCAG AA contrast failures — alpha-composited backgrounds, gradient text, `oklab()`/`oklch()` colors all handled
  98. - Text below 12px, images without alt
  99. - Text cut off by its own container (`line-clamp` and friends are not "clipped" — they are a decision)
  100. **Can you reach it**
  101. - Touch targets below 44px (mobile profiles only; inline text links exempt by width, per WCAG)
  102. - Controls painted over by something else — confirmed with `elementFromPoint`, not geometry, and sampled edge to edge so a floating button covering one end of a wide button is caught
  103. - Controls trapped under a fixed bar, or under the on-screen keyboard (`keyboard-audit` opens the keyboard the way a phone does and re-measures)
  104. - Content clipped by a container with no way to scroll to it — the same box with `overflow-x: auto` is fine, because the content is reachable
  105. - Text sliding behind a control when a row does not wrap
  106. - Horizontal overflow with the offending elements
  107. - Fixed bars sitting under the notch or home indicator — only when the page asked for the full screen (`viewport-fit=cover`) and then never used the inset it got back; without that flag iOS letterboxes the page and nothing can be hidden
  108. **Does it make sense**
  109. - A row of actions where every one looks identical, so nothing says which is primary — quiet on tabs, menus and filter chips, and only fires when mis-clicking costs something (save, delete, send, pay)
  110. - Light patches left behind in dark mode
  111. - Two languages in one screen, and US date formats in a non-US locale
  112. - "0 results" shown while a spinner is still turning — an intermediate state presented as the truth
  113. - An error message that names nothing ("An error occurred.") with no way out beside it
  114. - An irreversible action — delete, remove, delete account — on a page that owns no confirmation step at all; the button is never clicked, because clicking it really deletes
  115. - A permission asked for during load, before the person has done anything that would explain it
  116. - **Theme drift**: elements identical in light *and* dark = likely hard-coded colors
  117. - Console/JS errors and failed network requests per device
  118. Every check has a false-alarm test next to its detection test. That is not politeness: a tool that cries wolf on every bottom navigation bar gets ignored, and then its real findings go unread too.
  119. And the honest limit: automated checks cannot see *design* mistakes — a collided header measures fine. That's why `see_screen` exists and why the report says "eyeball the PNGs."
  120. ## Behaviour you cannot see by looking (offline, back)
  121. Two of these cannot be measured from a rendered page: the network has to
  122. actually drop, and the back button has to actually be pressed. Both run as panel
  123. actions, so the audit and the MCP tools share them.
  124. ```bash
  125. # through the panel
  126. curl -X POST localhost:5055/action -H 'x-uisight-token: ...' \
  127. -d '{"type":"offline-audit","session":"mobile"}'
  128. ```
  129. **Offline** drops the connection, reloads, and asks what the person is looking
  130. at: an explanation, a retry, a spinner that will never finish, or nothing. The
  131. distinction that keeps it honest is the service worker — a page without one
  132. *cannot* answer offline, so that result is marked `expected` and the audit
  133. filters it out. A page that registers a worker and still shows the browser's
  134. error page is a real finding. The connection is restored in a `finally`, so a
  135. failure never leaves the session stuck offline.
  136. **Back** follows an internal link and presses back, then checks that the address
  137. returned to where it started and that the screen is not empty. Coming back to a
  138. blank page is how "back" turns into "leave the app".
  139. ## Behind the login (`uisight-audit`)
  140. Public pages are the half of an app nobody lives in. Of four real bugs a person
  141. found by hand and sent in, three were behind a login and one showed up for a
  142. single role only.
  143. ```bash
  144. uisight-audit # every configured role, 10 pages each
  145. uisight-audit --roles guide,agency # only these
  146. uisight-audit --pages 20 --port 5062
  147. ```
  148. Accounts live in `~/.uisight/accounts.json`. Sign-in tries three routes: a fixed
  149. `code` (the store-review-account pattern), a `devCode` read straight out of the
  150. app's own OTP response (dev/demo mode — no stored secret at all), or a password
  151. field. Success means *leaving* the login page, not HTTP 200, so a wrong code is
  152. never reported as a win. When the app refuses, its own words are passed through:
  153. "HTTP 429 · too many codes requested" instead of a guess about demo mode.
  154. Roles are switched through the app's own view-as endpoint where it has one, so
  155. one admin account can audit every role. Pages not yet measured under any role go
  156. first, so a second role spends its budget on new ground instead of re-measuring
  157. the same public pages.
  158. ## Editor extension
  159. `extension/` is a VS Code / Antigravity extension: the live panel in the side
  160. bar, plus commands for device, theme, address, inspect and "send the screen to
  161. your AI".
  162. Search for `uisight` in the extensions panel of Antigravity, Cursor or
  163. VSCodium — [open-vsx.org/extension/sololabstr/uisight](https://open-vsx.org/extension/sololabstr/uisight).
  164. Node.js is the only requirement: the extension runs the published package
  165. through `npx uisight@latest`, so the engine updates itself and installing once
  166. keeps getting new checks.
  167. To build it from this repo instead:
  168. ```bash
  169. cd extension && npx @vscode/vsce package
  170. code --install-extension uisight-*.vsix
  171. ```
  172. The extension talks to the panel over HTTP and nothing type-checks that
  173. conversation, so `test/extension.test.mjs` compares the two sides: every action
  174. it sends must be one the server handles, every route must exist, every result
  175. field it renders must be one the engine produces, and every command in the
  176. manifest must be registered. That test exists because the pair drifted once and
  177. failed *silently* — Inspect reported "no findings" on pages full of them.
  178. ## What it costs
  179. Someone burned through a plan running this and had no way to see where it went.
  180. So here are measured numbers, not estimates — a Pixel 7 session on a real site,
  181. with an image priced the way Claude prices one (width x height / 750):
  182. | | tokens |
  183. |---|---|
  184. | `uisight <url>` then read `REPORT.md` | **~800, once** |
  185. | `uisight-audit` then read `REPORT.md` | **~150-800, once** |
  186. | MCP `inspect` | ~570 per call |
  187. | MCP `see_screen` | ~260 per call (0.75 scale, the default) |
  188. | MCP `see_screen` with `full` | ~2,000 per call (capped; was ~5,800 uncapped) |
  189. | tool definitions | ~1,065 **per request** |
  190. Three things follow from that table.
  191. **The CLI is the cheap path and it is not close.** `uisight` and `uisight-audit`
  192. write a file; the model reads it once. Driving the MCP tools screen by screen
  193. re-sends the whole conversation on every step, so thirty round trips cost far
  194. more than one report. Reach for the MCP tools when you need to *act* on a page —
  195. tap something, change device, look at a specific state — not to survey an app.
  196. **An image is not paid once.** It stays in the conversation and is re-sent on
  197. every later turn. That is why `inspect` exists and why its output is text: the
  198. same page costs ~570 tokens measured versus ~460 seen, and the measurement says
  199. `4.38:1 (threshold 4.5)` where the picture only lets the model guess. A full-page
  200. capture is now capped (`UISIGHT_MAX_IMAGE_TOKENS`, default 2000) and the response
  201. tells you what it cost and what was left out, instead of quietly spending.
  202. **A screenshot does not need to be full size.** Measured on a real page: the
  203. same mobile screen is 461 tokens at 1.0, 259 at 0.75 and 115 at 0.5 — and cost
  204. falls with the *square* of the scale. At 0.75 it is indistinguishable, small
  205. print included; at 0.5 the layout and every meaningful label still read and only
  206. the smallest legal text goes soft. So 0.75 is the default and `scale` is a
  207. parameter on `see_screen`; pass `1` when small print is the thing you are
  208. looking at, `0.5` for a cheap sweep.
  209. **Tool definitions are a fixed tax on every request.** Nine tools cost ~1,065
  210. tokens whether you call them or not:
  211. ```jsonc
  212. // only what a measuring session needs: goto, inspect, see_screen, status
  213. { "env": { "UISIGHT_TOOLS": "core" } } // ~419 tokens
  214. { "env": { "UISIGHT_TOOLS": "goto,inspect" } } // ~211 tokens
  215. ```
  216. ## Something didn't work?
  217. Please open an issue — even a one-liner. This is a young project and the fastest way it improves is someone saying "I ran it on X and got Y". Screenshots of the panel or the contents of `REPORT.md` help a lot.
  218. Known rough edges, so you can tell a bug from a limitation:
  219. - **Design mistakes are invisible to the engine.** A header that collides with the logo measures perfectly fine. Use `see_screen` and look.
  220. - **Photo backgrounds are skipped.** Contrast over a background image can't be computed from CSS, so those elements are left alone rather than guessed at.
  221. - **Theme drift samples structural elements** (body, header, nav, main, footer, button, a, input, cards/panels/modals/menus) — drift that lives only in body copy won't show up in the light↔dark comparison.
  222. - **iPhone profiles are WebKit, not an iOS Simulator** — very close to Safari, not identical to a device.
  223. - **Internals are still Turkish.** Public surfaces (tools, CLI flags, reports) are English; variable names inside `src/` aren't yet. PRs welcome either way.
  224. ## Development
  225. ```bash
  226. npm install
  227. npx playwright install chromium
  228. npm test # runs the inspection engine against fixture pages in a real browser
  229. ```
  230. The tests are regression locks: every case in `test/inspect.test.mjs` is something the engine got wrong at least once — a false "clean" verdict, a false alarm, or a measurement that silently skipped a color format.
  231. See [CONTRIBUTING.md](CONTRIBUTING.md) before touching the measurement engine — it explains why the color math cannot be extracted into a module, and what a good bug report looks like.
  232. ## Notes & limitations
  233. - iPhone profiles run on real WebKit (Safari's engine) — close to iOS, but not an iOS Simulator.
  234. - Browsers are downloaded once by Playwright on first run (`npx playwright install chromium webkit` if you want to pre-warm).
  235. - Everything runs **locally** — no cloud, no account, your screens never leave your machine.
  236. - As of v0.2 the codebase is English throughout — identifiers, comments, and the panel's HTTP field names. If you were calling the panel API directly, [CHANGELOG.md](CHANGELOG.md) has the rename table.
  237. ## License
  238. MIT © [SoloLabs](https://sololabs.com.tr)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.