Verification browser for coding agents: headless WebKit, DOM eval, screenshots, pixel-diff.
io.github.hongnoul/hwatu MCP Server
This MCP server provides a verification browser for coding agents, using headless WebKit. It supports DOM evaluation, generates screenshots, and performs pixel-diff comparisons to validate rendered output. The server is associated with tooling for browser automation and visual verification in agent workflows.
π οΈ Key Features
Headless WebKit browser
DOM eval for page inspection
Screenshot capture
Pixel-diff visual verification
π Use Cases
Visual verification of coding-agent browser output
Automated checks that rendered UI matches expected pixels
DOM-based inspection during verification runs
β‘ Developer Benefits
Supports agent tooling via MCP
Combines browser automation with visual verification
Uses Linux-focused browser components (Wayland/GTK noted in topics)
β οΈ Limitations
Described specifically as a verification browser (not general browsing for arbitrary workloads)
hwatu is a headless verification harness for coding agents: a warm
WebKit daemon driven over CLI, MCP, or one JSON line per Unix-socket
connection. Instead of "looks right to me", the agent gets one-call
verified page checks in ~35 ms, pixel-diff scores it can climb,
animations as numbers, and headless windows that never steal
focus, at any parallelism. Jcode drives it natively as its browser
backend. When a check needs a human (a CAPTCHA, a judgment call),
hwatu focus <id> materializes the same live session as a real window.
Or skip MCP: every command is a short CLI call or one newline-delimited
JSON line over a Unix socket.
Connecting hwatu makes its tools available; a project instruction tells
the agent when to use them. Add this to AGENTS.md, CLAUDE.md, or
Cursor rules:
markdown
## Frontend verification
Use Hwatu after frontend changes. Exercise the affected user journey and
verify its intended visible, navigational, or persisted result with `expect`.
A successful click or clean console is not proof of success. Check `console`
for additional JavaScript and request failures after verifying the outcome.
Then make the task's proof concrete:
text
Implement display-name editing on /settings. Use Hwatu to enter βTest User,β
save it, verify the visible success state, reload, confirm persistence, and
report any console errors.
The verification loop:
sh
hwatu --headless localhost:3000 # its window; you never see it
hwatu --headless staging.example.com # the reference
hwatu diff --id 2 --other 1 --heatmap /tmp/heat.png
# {"match_percent":85.13,"regions":[{"x":0,"y":160,"w":2048,...}]}
hwatu motion --id 1 # the reference's animations, as numbers# easing cubic-bezier(0.25,1,0.5,1), 300ms, marquee 29.78px/s ...# ...agent edits code...
hwatu diff --id 2 --other 1
# {"match_percent":97.49} # climbing beats guessing
This loop took a clone of stripe.com's landing page from 85.1% to
98.8% pixel match. Reproduce it: scripts/demo/. A
second real-agent scenario (four responsive viewport diffs, then live
human hand-off) with evidence manifests:
scripts/demo-aiuc/.
A full verification pass (open, load, eval, screenshot, close) is
one command, one tool call, ~35 ms median
(benchmarks):
For a repeatable repo-level contract that also owns the preflight, local dev
server, responsive screenshots, source-staleness check, and evidence report:
sh
hwatu verify .hwatu/about.verify.json
The same executor is exposed to MCP clients as verify_ui, so agent
harnesses do not rebuild the orchestration loop. See the
agent guide.
Generated HTML in hand and no server? hwatu render is the same
one-call pass with the markup as input: no temp file, no
python3 -m http.server:
sh
echo'<h1>generated</h1>' | hwatu render --stdin --shot=/tmp/gen.png
# {"rendered":true,"shot":"/tmp/gen.png","load_ms":5,"total_ms":28}# React to load, console, download, and window events without polling.
hwatu watch --kinds load,console
# {"event":"load","seq":1,"window_id":7,"data":{"state":"started",...}}
MCP clients call subscribe_events for the same stream as
notifications/hwatu/event. Full protocol and verification loops:
agent guide.
Elsewhere, headless is decided at launch and a human can never see
the session. In hwatu it is a window property, switchable live, in
both directions: hwatu focus <id> promotes any headless session to
a real window for the human, state intact.
challenge is detection and hand-off only, by design: no solver
APIs, no token injection, no fingerprint games.
The hand-off destination
The hand-off works because hwatu is also a real browser, built for
tiling WMs. hwatu <url> opens a window like your terminal opens a
shell (your WM is the tab bar, there is none in the window):
mainstream keybinds (ctrl+l, ctrl+f, ctrl+k palette,
rebindable), native ad blocking (~119k EasyList rules compiled into
WebKit's content-extension engine, zero JS in the request path),
Chromium-curve scrolling, and unified shortform controls. Every
window shares the one warm daemon (~56 MB per extra window),
suspends when unfocused, and crash-restores at its last URL. Honest
gaps: no Widevine or passkeys in WebKitGTK. WM configs
(hyprland, sway,
niri), keybinds, and setup:
docs/human.md.
Push event subscriptions as JSON lines or MCP notifications (watch)
One-call page assertions with polling (expect)
CAPTCHA / anti-bot detection with structured wait/resume (challenge)
MCP server, plain CLI, and a 1-line JSON socket protocol
A real browser as the hand-off destination: keybinds, media, ad blocking, crash restore
Why not Playwright or chrome-devtools-mcp?
Three ways to give an agent a browser:
How it runs
What it costs the agent loop
Cold library (Playwright, launched per task)
engine starts when the script does
fast to call, slow to run: every check pays engine startup; no state survives between tasks
Warm browser (your Chrome + devtools-mcp)
a full human browser stays resident
resources spent on tabs, extensions, sync, UI you never render, and its windows steal your focus while you work
hwatu
"the coldest warm daemon": engine hot, everything else absent
8 ms spawns, 35 ms verified checks, invisible until you ask to see it (focus), interruptible in both directions
hwatu keeps exactly what makes checks instant (engine, GPU context,
compiled adblock, a prewarmed WebView) and nothing that serves a
human unless that human asked for a window. That is why it idles
warm without a tab bar, and why a kept-warm Playwright server driven
the same way costs 341 ms per client to hwatu's 39
(benchmarks).
The second difference is what comes back. Playwright and
chrome-devtools-mcp are automation APIs: they let an agent drive a
browser, then hand back raw screenshots and DOM to eyeball. hwatu is
a verification browser: the measurement primitives (check,
diff, motion, expect) are built in, a window costs 13 ms, and
headless is a window property, not a launch mode.
Verify pass as a warm service (fresh client per check)
341 ms
n/a
39 ms
Tool calls per verify pass
5
5
1
Pixel-diff score + regions + heatmap
π‘ 1
β
β
Animations as numbers, pinned mid-flight
β 2
π‘ 3
β
Headless β headed on a live session
β
β
β
Human hand-off mid-session, state intact
β
β
β
No focus stealing at N parallel agents
π‘ 4
π‘ 4
β
CAPTCHA detection + structured wait/resume
β
β
β
No Node, no per-version browser download
β
β
β
1 toHaveScreenshot compares against stored goldens: pass/fail for
test suites, not a score an agent can climb.
2 Standard practice is to disable animations or fast-forward to the
end state to avoid flakes.
3 Raw CDP can query animation state, but there is no numeric
summary of easing/velocity/keyframes.
4 Fine headless; every headed window pops and takes focus.
Comparison reflects each project at the time of writing;
corrections are welcome. Honest caveats: Playwright still wins
cold start (190 vs 435 ms, paid once per boot) and memory; hwatu
renders WebKit not Chromium (keep a Playwright matrix in CI for
engine-specific bugs), and it is Linux-only today. Full
head-to-head data and methodology:
docs/benchmarks.md.
What about Claude in Chrome? Different category. Claude in
Chrome is one agent product driving your Chrome through an
extension, sharing your profile, tabs, and focus, callable by nothing
else. hwatu is a client-agnostic daemon any agent calls over CLI/MCP,
with its own warm WebKit engine, headless by default, and
verification primitives built in. Use Claude in Chrome to let Claude
browse alongside you; use hwatu when agents need cheap, repeated,
measurable page checks.
Feedback
A successful check, a failed install, a missing keybind, and a site
that broke are all useful signals. Share a two-minute
use report
or report a bug.