[Mantis, a rainbow mantis shrimp wearing boxing gloves]
Mantis
Sees 12 color channels. You see 3. Your coding agent sees 0.
English · Tiếng Việt · 简体中文
[CI]
[Early development]
[MIT license]
[Agent Skills format]
[Playwright]
[Mantis in 60 seconds: an agent says it fixed the layout but hid the menu button, and Mantis catches the cover-up]
▶ 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:
- opens the real app;
- checks every screen size, both themes and every language you ship;
- boxes what is broken in red;
- fixes it at the root, and flags any "fix" that only hides the bug;
- proves it with before/after screenshots;
- measures how fast it is on a slow phone, ranks the fixes, and catches speed-ups that only remove content (from v0.6).
[A Mantis contact sheet: every page on mobile, tablet and desktop, in light and dark mode, with problems boxed in red]
What it catches
How it works
- Look.
/mantis runs the app through every screen × theme × language in
a real browser and writes a report the agent reads, with annotated
screenshots.
- 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.
- Prove.
/mantis-proof makes a before/after sheet, a close-up of one
fixed finding, and optionally a video, for your pull request.
- 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).
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):
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).
[Mantis fix receipt: the same 24 screens before and after the fixes, errors going from 14 to 0, with 0 cover-ups]
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:
A cover-up is an error, so the run still fails. When the fix is honest, the run
ends with a receipt:
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.
[A Mantis perf sheet: LCP, blocking time and layout shift rated against Core Web Vitals, a filmstrip with the LCP frame circled, a waterfall of the requests that matter, the first five fixes and what each third party costs]
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:
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:
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.
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.
[A Mantis house-style sheet: the light and dark palettes with their CSS tokens, the type scale in the app's own words, corner radii, spacing and near-duplicate colors]
/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:
Pages behind a login
Give Mantis a Playwright storage state and every screen starts signed in:
If the app only keeps a flag in localStorage (onboarding done, a demo session), write the file by hand:
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, …):
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
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:
MCP server (from v0.7). Any MCP client (Claude Desktop, Cursor, VS Code, Codex, Windsurf, …) can call Mantis as tools:
The tools take the same options as the CLI, with progress while they run. Reports land in .mantis/ in the server's working directory.
Other clients take the same command in their MCP settings:
A look takes seconds and a perf run a minute or more, so allow a long tool timeout in your client.
Just the CLI
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:
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.
