Mantis

Mantis

Sees 12 color channels. You see 3. Your coding agent sees 0.

English · Tiếng Việt · 简体中文

_{▶ Watch the 60-second intro (MP4, 4 MB) · 1080p}

---

Your coding agent builds UI with its eyes closed. It writes the CSS, says "Done ✅", and never opens the browser.

Then someone opens the page on a phone:

• the menu runs off the screen;
• in dark mode one card is still white, with white text on it;
• the Vietnamese button label is cut in half.

Mantis catches the UI bugs your agent can't see, and the ones it hides. It:

1. opens the real app;
2. checks every screen size, both themes and every language you ship;
3. boxes what is broken in red;
4. fixes it at the root, and flags any "fix" that only hides the bug;
5. proves it with before/after screenshots;
6. measures how fast it is on a slow phone, ranks the fixes, and catches speed-ups that only remove content (from v0.6).

What it catches

Problem	What you see	Why agents miss it
Page overflow	Sideways scrolling on a phone	They picture the desktop layout
Cut-off text	"Đăng ký nhận bản ti…"	They test with short English strings
Right-to-left mistakes	Arabic laid out left to right, a row cut off on the left	They never switch the page to dir="rtl"
Overlap	A badge sitting on top of a button	Absolute positioning looks fine at one width
Contrast	Gray text you can barely read	Colors are chosen in code, never seen
Dark-mode leaks	One white card in a dark page	A hard-coded #fff the theme can't reach
Tiny tap targets	16px icon buttons on a phone	A mouse is precise, a thumb isn't
Console errors, broken images	Red errors, empty boxes	Nobody opened DevTools
Layout shift	Content jumps while you read	Everything loads instantly on localhost
Off-style values	A blue one shade off your brand, a 15px corner among 16px ones	They hard-code a value instead of using your token
Slow pages (mantis perf)	A 5 s wait on a phone, API calls in a row, a chat widget holding the page	Localhost on a laptop is fast

How it works

1. Look. /mantis runs the app through every screen × theme × language in a real browser and writes a report the agent reads, with annotated screenshots.
2. Fix. /mantis-fix fixes causes, not symptoms. It never puts overflow-x: hidden on the body, shrinks text until it fits, or turns dark mode off, and the next run checks that it didn't.
3. Prove. /mantis-proof makes a before/after sheet, a close-up of one fixed finding, and optionally a video, for your pull request.
4. Speed. /mantis-perf measures the page like a phone on slow 4G, fixes what slows it down in order of impact and risk, and checks that the page got faster, not emptier (see below).

mantis look http://localhost:3000 --routes /,/settings --locales en,vi

Each language cell sets the browser locale and Accept-Language. Many apps pick their language another way, and --locale-strategy handles that (from v0.5):

The app switches language by	Pass
a URL prefix, e.g. /vi/settings	--locale-strategy path:/{locale}
a query parameter	--locale-strategy query:lang
a cookie (next-intl, Rails)	--locale-strategy cookie:NEXT_LOCALE
localStorage (i18next)	--locale-strategy storage:i18nextLng

A language whose page text comes out the same as the first one is reported as "not localized". That usually means the strategy is wrong.

No translations yet? Add the pseudo-locale (from v0.5): --locales en,pseudo. That cell loads the first language and rewrites every visible string the way translations grow. "Subscribe" becomes [Šûƀƀšççŕîîƀéé]: accented, about 40% longer, and bracketed, so a missing ] shows the end was cut. Text the app renders later is rewritten too. Code, form input and translate="no" content are left alone. The pseudo-locale finds layouts that break with longer text. It can't tell which strings are hard-coded, because it rewrites them all.

Right to left. Arabic, Hebrew, Persian and Urdu pages start at the right edge and overflow to the left. Mantis checks them the same way, mirrored. It also reports an error when such a page is laid out left to right because dir="rtl" is missing. To see how an app without those languages would cope, use --locales en,pseudo-rtl: the pseudo-locale, laid out right to left (from v0.5).

Fixed, or just hidden?

An agent told to make the report clean can make it clean without fixing anything. Every mantis look compares itself with the previous run of the same URL, so these tricks don't work:

Trick	What Mantis reports
overflow-x: hidden on html, body or the app root	The overflow, still: the element that is cut off, and the rule that hides it
Hide the broken element (display: none, visibility: hidden, opacity: 0)	cover-up: the issue is gone, but so is the element
Hide the other element of an overlap	cover-up on that element
Shrink the text until it fits	cover-up: 16px → 7px
Clip it, or cut the text short	cover-up: less of it is visible, or fewer characters
A button, link or heading quietly disappears	lost warning

A cover-up is an error, so the run still fails. When the fix is honest, the run ends with a receipt:

Mantis: 0 errors, 0 warnings in 24 cells
  vs 2026-10-29T11-51-22: 18 fixed · 0 new · 0 cover-ups · 0 lost

Faster, or just emptier? (mantis perf, from v0.6)

Ask an agent to make a page faster and it may remove the hero image, cut the list to five rows, or lazy-load what the first screen shows. The numbers get better, and the page gets worse. mantis perf measures the page, says what makes it slow down to the line of code, ranks the fixes by impact and risk, and fails the run when a "speed-up" only removed content.

mantis perf http://localhost:4173 --routes /,/pricing

Measures like a phone. Every route gets N cold visits (--runs 5 by default) in Chromium. The default profile is a mid-range phone on slow 4G: 4× slower CPU, 562 ms round trips. --profile desktop turns the throttling off. You get the median and spread of LCP, FCP, TBT, CLS, TTFB, when the API data was in, bytes and requests. A development server is called out, since its numbers are not what users get.

One more visit runs without throttling, because throttling hides what it touches:

• the server's real wait per request;
• a CPU profile that names the functions the main thread spent its time in;
• coverage of the code that never ran.

Says what to fix, ranked. perf.md starts with the fixes:

bucket	means
Do first	worth it, low risk
Plan	worth it, the fix needs care
Nice to have	small gains
Your call	a product decision, such as dropping a vendor

Each fix names a culprit the agent can open. That is a selector, a URL, or file:line with the function and its callers (loadConfig /app.js:4 ← main /app.js:51). It also gives the metric the fix moves with an estimated saving and how sure that estimate is, and the detected framework's own way to fix it (Next.js, Nuxt, Angular, Vue, React, SvelteKit). It finds:

• an LCP image that is lazy-loaded or found late;
• images much larger than they are drawn;
• files in <head> that hold the first paint;
• functions that hold the main thread;
• code that never runs;
• fonts that hide text;
• layout shifts and what caused them (an image without a size, a banner inserted above, a list filled late);
• a slow HTML response.

Slow APIs. Every API call is traced to the code that made it. Mantis finds:

• endpoints that are slow on the server;
• calls that wait for each other;
• the same call made twice;
• one call per item (N+1);
• large JSON;
• a first call that starts late, with the script it waited for.

Third parties. Grouped by vendor (Google Analytics, Intercom, YouTube, Stripe and about 50 more): their bytes, main-thread time, render-blocking files and iframes. Each kind gets its fix: a facade for chat and video, analytics after the page is interactive, self-hosted fonts. Whether a costly vendor is worth it goes under "Your call".

A receipt you can trust. Run it again after a fix and it compares itself with the previous run of the same URL and profile:

vs 2026-10-30T12-32-02: LCP 2.5 s → 36 ms · TBT 121 ms → 0 ms · CLS 0.164 → 0 · transferred 551 KB → 354 KB · 11 fixed · 0 new · 0 cover-ups

A change counts only beyond the noise, meaning both runs' spread. Anything else is shown as ≈. A route that got faster because its LCP image, its text, its first-screen images, headings or controls went away is a cover-up error: "Faster, or just emptier?". Findings that left with the content are not counted as fixed.

Is this Lighthouse? Lighthouse scores a page. mantis perf is built for the agent loop:

• a culprit down to the function and the call stack;
• fixes ranked by risk as well as impact;
• API and vendor findings with their fixes;
• medians over several cold runs;
• a before/after receipt that refuses to count removed content as a speed-up.

Numbers

What has been measured so far:

• Planted bugs. fixtures/buggy-app has 13 planted UI bugs, listed in PLANTED.json. Mantis reports every one of them in exactly the screen, theme and language cells where it was planted, and nothing else. On fixtures/clean-app, the same app with every bug fixed, it reports zero issues. Both checks run in CI.

• Cover-ups. Four tricks applied to buggy-app behind the same URL (hide the overflow with overflow-x: hidden, hide the menu button, hide the button it overlaps, shrink a label to 7px) are all still reported or flagged as cover-ups. Swapping in clean-app, the honest fix, gives every issue fixed, 0 new, 0 cover-ups and 0 lost. This runs in CI too.

• Cover-up false alarms. Two runs in a row on tailwindcss.com, vercel.com, notion.com and stripe.com reported 0 cover-ups and 0 lost controls. On vnexpress.net, where the news changes between runs, they reported 0 cover-ups and one grouped "lost" warning. Checked on 2026-10-29.

• Real sites. On 10 public sites (example.com, playwright.dev, Hacker News, tailwindcss.com, MDN, svelte.dev, react.dev, gov.uk, vercel.com and stripe.com), 18 of the 21 errors it reported held up when checked by hand. The 3 false positives were demo frames on tailwindcss.com. Checked on 2026-10-26.

• House style. On buggy-app, mantis learn lists exactly the 3 near-duplicates planted there:

  • a color ΔE 0.4 from --muted;
  • a 13.6px label in a 14px scale;
  • a 15px corner next to --radius: 16px.

  On clean-app it finds none. Each of four near copies hard-coded into clean-app (a color, a font size, a radius and a font) gives one off-style warning; a clearly new color gives none. These checks run in CI.

• Off-style false alarms. Learning a public page and looking at it again right away gave 0 off-style warnings on tailwindcss.com and vercel.com. stripe.com gave 2, linear.app 4 and github.com 4. All 10 were inside live product demos or a lazily loaded repo grid, whose content changes between loads. Checked on 2026-10-29.

Agent benchmark

The same agent (Claude Code, Opus 5.5 and Haiku 5.5) did the same UI tasks with and without the Mantis skills, 3 runs per cell, graded by a hidden Playwright grader that never uses Mantis's detectors. Everything is in bench/: the method, the planted bugs, the graders, every agent's final report and diff, the ties and the losses.

• Mantis did not make Opus 5.5 fix more bugs. It tied on two small apps (13.0 vs 12.7 of 13, 9 vs 9 of 9). On a fork of Excalidraw it was behind with v0.3.1 (6.0 vs 6.7 of 7) and ahead with v0.4.0 (7.0 vs 6.7). Those fixes were tuned on that same fork.
• Under pressure, it got hidden bugs reported. Told "make check:ui pass, keep it small", both arms fixed only what the check covers. With Mantis, the final report also listed the bugs the check can't see: 3.7 of 5 against 1.7 (Opus, Atlas), and 4 of 4 in every run against 0 (Opus, Excalidraw, v0.4.0).
• When Mantis is blind, the agent is too. With v0.3.1, which could not measure contrast on a canvas, agents using Mantis fixed a 1.27:1 button less often than agents without it.
• No agent in either arm covered a bug up: 0 in 72 graded runs.

Why not …?

A browser MCP or a screenshot script? Playwright MCP, Chrome DevTools MCP and agent-browser give the agent a browser. The agent still has to decide which screens to open and judge each screenshot by eye. Mantis runs on Playwright and adds the parts an agent skips:

• the same matrix every time: phone, tablet and desktop × light and dark × every language;
• detectors that name the element and give the measurements behind each finding;
• a comparison with the last run that catches fixes which only hide a bug.

In our benchmarks, Opus 5.5 without Mantis wrote its own Playwright scripts and fixed about as many bugs. The difference was under pressure: with Mantis, the agent still told the user what the CI check couldn't see.

ProofShot? ProofShot records what the agent did (video, screenshots and errors) into a proof bundle you can review. Mantis checks for specific kinds of breakage across the matrix, and fails the run when a fix only hides one. One answers "what happened?"; the other answers "is it broken, and was it really fixed?"

Impeccable? Impeccable's detect checks a page against design rules, so the UI doesn't look generic. Mantis checks that it works: nothing overflows, every label is readable in both themes and every language, and fixes are real. Impeccable makes it tasteful; Mantis proves it isn't broken. Use both.

Visual regression (Percy, Chromatic, BackstopJS)? These compare screenshots with an approved baseline and ask a person to review each change. Mantis finds bugs on the first run, with no baseline, and says what is wrong and where. It compares with the previous run only to catch cover-ups.

Mantis has no taste. It has yours.

mantis learn opens the running app and measures the house style it actually uses, with no design spec to write first:

• the colors in each theme, with the CSS variables behind them;
• font sizes, fonts and weights;
• corner radii, spacing, shadows and motion timing.

mantis learn http://localhost:3000 --routes /,/settings

It writes .mantis/style.json for the agent, style.md for people, and a style.png sheet. From then on, look checks every page against that style. It warns off-style when a page uses:

• a color within ΔE 5 of a house color without being one of them, such as a hard-coded copy of --primary;
• a font size or corner radius a pixel or two off the house values;
• a font the app uses nowhere else.

Values far from everything are left alone, since a new illustration color can be on purpose. The sheet also lists the near-duplicates already in the app.

/mantis-fix reads style.json before it writes CSS and reuses the house values instead of inventing new ones.

Mantis puts a .gitignore in .mantis/, so reports, screenshots and saved sessions stay out of git. To share the house style with your team, commit it on purpose: git add -f .mantis/style.json.

Your project on the sheets

The contact sheet and the proof carry your project's name and a link and QR code to its repo, read from package.json and the git remote. Add a .mantis.json to change them:

{ "name": "Lumen", "logo": "public/logo.svg", "brandColor": "#4f46e5", "repo": "acme/lumen", "qr": true }

Pages behind a login

Give Mantis a Playwright storage state and every screen starts signed in:

npx playwright codegen --save-storage=.mantis/auth.json http://localhost:3000/login   # sign in, close the window
mantis look http://localhost:3000 --routes /dashboard,/settings --storage-state .mantis/auth.json

If the app only keeps a flag in localStorage (onboarding done, a demo session), write the file by hand:

{ "cookies": [], "origins": [{ "origin": "http://localhost:3000", "localStorage": [{ "name": "onboarded", "value": "1" }] }] }

The file holds a live session, so keep it out of git. Inside .mantis/ it already is: Mantis writes a .gitignore there. proof --video takes the same flag. A run is only compared with earlier runs that used a storage state file of the same name.

On every pull request (GitHub Action, from v0.7)

The action checks a pull request's preview deployment and compares it with your live site, which shows what the change fixed, broke or only hid. It posts the result as a pull request comment, updated on every push, and as the job summary. The sheets and screenshots are uploaded as an artifact.

With a host that reports preview deployments to GitHub (Vercel, Netlify, …):

name: Mantis
on: deployment_status
permissions:
  contents: read
  pull-requests: write
jobs:
  look:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: vulinh1704/[email protected]
        with:
          url: ${{ github.event.deployment_status.target_url }}
          baseline-url: https://your-app.com
          routes: /,/pricing,/settings
          locales: en,vi

Or build and serve the app in the job, and point url at it (http://localhost:4173).

• command: perf measures speed instead. The comment shows the metrics per route, the receipt against the baseline and the first fixes. A speed-up that only removed content fails the check.

• fail-on follows the exit code by default:

  • look fails on any error;
  • perf fails when there is something to do first or to plan;
  • both fail on a cover-up.

  Set fail-on: cover-ups to fail only when a fix hid the problem, or fail-on: never to only report.

• Inputs: routes, viewports, schemes, locales, locale-strategy, dark-strategy, runs, profile and args (anything else) map to the CLI's options.

• Outputs: errors, warnings, cover-ups, exit-code, report and artifact-url.

• Forks: a pull request from a fork gets a read-only token. The action then writes the result to the job summary only.

Install

Mantis is in early development (v0.7). Expect rough edges, and please open an issue when it gets something wrong.

Claude Code

/plugin marketplace add vulinh1704/mantis
/plugin install mantis@mantis

Other agents. The skills use the open SKILL.md format, so agents that load skills (Codex, Cursor, GitHub Copilot, Gemini CLI and others) can install them with:

npx skills add vulinh1704/mantis

MCP server (from v0.7). Any MCP client (Claude Desktop, Cursor, VS Code, Codex, Windsurf, …) can call Mantis as tools:

Tool	What it returns
mantis_look	The report and the contact sheet, with fixes and cover-ups compared with the last run
mantis_perf	The ranked fixes and the perf sheet, with the before/after receipt
mantis_learn	The house style and its sheet
mantis_proof	The before/after sheet of two runs

The tools take the same options as the CLI, with progress while they run. Reports land in .mantis/ in the server's working directory.

claude mcp add mantis -- npx -y @vulinh1704/mantis mcp

Other clients take the same command in their MCP settings:

{ "mcpServers": { "mantis": { "command": "npx", "args": ["-y", "@vulinh1704/mantis", "mcp"] } } }

A look takes seconds and a perf run a minute or more, so allow a long tool timeout in your client.

Just the CLI

npx -y @vulinh1704/mantis look http://localhost:3000
# or install it: npm i -g @vulinh1704/mantis

Mantis drives Chromium through Playwright. If the browser isn't installed yet, run npx playwright install chromium. Node.js 20 or newer.

Docker. No Node or browser to install. The image comes with Chromium, ffmpeg and the fonts the sheets use, for linux/amd64 and linux/arm64:

# Docker Desktop (Mac, Windows): reach the dev server through host.docker.internal
docker run --rm -v "$PWD:/work" ghcr.io/vulinh1704/mantis look http://host.docker.internal:3000

# Linux: share the host's network, and own the files it writes
docker run --rm --network host --user "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/vulinh1704/mantis look http://localhost:3000

The report lands in ./.mantis as usual. A storage state file in the mounted directory works as --storage-state .mantis/auth.json.

Limits

• Mantis checks that the page works, not that it is beautiful. Use it with a design skill.
• It doesn't click through flows or check hover and focus states yet.
• It doesn't measure animation smoothness yet.
• Cover-up checks need a previous run of the same URL to compare with. Layout shift, console and network issues change by themselves on live pages, so they are not checked for cover-ups.
• Off-style compares values, not intent. Content that changes between loads, such as product demos, carousels and feeds, can show values the learn run never saw. Leave such regions out with --ignore.
• Contrast and dark-mode checks read the screenshot when the page code can't tell the background: text on a <canvas> (whiteboards, maps, editors) or under transparent layers. Product mockups drawn in HTML on a marketing page are measured like any other text; leave them out with --ignore if they are decoration. Text over photos, CSS background images and gradients is still not checked.
• mantis perf measures in the lab, in Chromium, with emulated throttling. That is not field data from your users. INP needs real interactions, so TBT and long animation frames stand in for it. A busy machine adds noise; the spread of the runs shows it. Savings are estimates: measure again after each fix.

Why a mantis shrimp?

It has 12 kinds of color receptors; you have 3. It also throws one of the fastest punches in the animal kingdom. It sees the bug, then it hits the bug.

License

MIT © Truong Dang Vu Linh. Built on Playwright and axe-core.