hwatu

• STOP your agent claiming "pixel-perfect." Make it prove 97.49%.
• STOP paying 5 tool calls per page check. hwatu check is one call, ~35 ms (beats warm-server Playwright ~9x).
• STOP browser windows stealing your focus. Headless by default, you keep typing.
• STOP shipping 170 MB of Chromium. One static binary + your distro's webkitgtk.

Documents

• Agent guide: protocol, primitives, verification loops
• Human guide: the tiling-WM browser side
• Benchmarks: every number, measured, with methodology
• Roadmap: plan of record, priorities, non-goals

Quick Start

Install → Detect workflow → Connect agent → Verify page → Hand off to human

curl -fsSL https://raw.githubusercontent.com/hongnoul/hwatu/main/scripts/install.sh | bash
hwatu setup

One static binary plus your distro's webkitgtk-6.0 (the installerchecks). On Arch: yay -S hwatu. From source: cargo build --release.

The installer installs binaries only. hwatu setup detects supported codingagents and prints the available connections without changing their config.Choose a client explicitly when you are ready:

hwatu doctor
hwatu setup --client claude --scope project --dry-run
hwatu setup --client claude --scope project
hwatu demo

• Install: download two binaries and check WebKitGTK.
• Detect: find Claude Code, Cursor, Jcode, or a generic MCP workflow.
• Connect: use Jcode's native socket, MCP, or the CLI fallback.
• Verify: run a headless rendered smoke test with doctor or demo.
• Hand off: materialize the same live session only when a human is needed.

Setup is previewable, idempotent, and reversible with the same client andscope plus --undo. Project scope creates shareable configuration; user scopekeeps it personal. Claude Code asks each user to approve project-scoped MCPservers when it next starts.

Manual MCP configuration remains one portable entry:

{ "mcpServers": { "hwatu": { "command": "hwatu", "args": ["mcp"] } } }

Or skip MCP entirely: every command is a short CLI call or onenewline-delimited JSON line over a Unix socket.

hwatu localhost:3000       # open a window like you open a terminal

Features

• Pixel-diff scoring: match percent + diff regions + heatmap (diff)
• Animations as numbers: duration, easing, velocity (motion)
• Deterministic animation frames: pin all animations at time t (seek)
• Page state as JSON, tokens not pixels (snapshot)
• Real input events with structured errors (click / type / scroll / upload)
• JS errors, console output, failed requests (console)
• One-call page assertions with polling (expect)
• Headless / background / focused as a per-window property, switchable live
• Human hand-off: hwatu focus <id> drops the live session into your tiling WM
• CAPTCHA / anti-bot detection with structured wait/resume (challenge)
• MCP server, plain CLI, and a 1-line JSON socket protocol
• A minimal WebKit browser for humans: native ad blocking, vim-style bar, crash restore

Why not Playwright or chrome-devtools-mcp?

There are three ways to give an agent a browser, and two of them are bad at it:

hwatu keeps exactly what makes checks instant (engine, GPU context,compiled adblock, a prewarmed WebView) and nothing that serves ahuman sitting in front of it. That's why it idles warm without a tabbar, and why a kept-warm Playwright server driven the same way stillcosts 341 ms per client to hwatu's 39 (benchmarks).

The second difference is what comes back. Playwright andchrome-devtools-mcp are, at their core, automationAPIs: they let an agent drive a browser, then hand back rawscreenshots and DOM for the agent to eyeball.

hwatu is different. It is a verification browser: the measurementprimitives are built in, and the browser itself is a warm daemonwhere a window costs 13 ms and headless is a window property, not alaunch mode.

That is why the loop looks like this, real commands, real output:

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

We ran this loop against a clone of stripe.com's landing page: anagent took it from 85.1% to 98.8% pixel match. Reproduce it:scripts/demo/. A full verification pass (open, load,eval, screenshot, close) is one command, one tool call, ~35 msmedian (benchmarks):

hwatu check localhost:5173 --eval 'document.title' --shot=/tmp/after.png
# {"title":"My App","eval":"My App","shot":"/tmp/after.png",
#  "console":[...],"load_ms":13,"total_ms":35}

The same pass through Playwright's warm in-process CDP connection,its best case, is 82 ms and five API calls. Shaped like hwatuactually runs (a fresh client each check against a kept-warmengine), Playwright's pass is 341 ms vs hwatu's 39: hwatu is awarm daemon by design, Playwright is a library you have to keep warmyourself.

And when the agent hits a CAPTCHA or a judgment call, hwatu focusmaterializes its live session, cookies and state intact, in yourtiling WM. You act for ten seconds. It takes back over. This isthe adjective no other tool gets to claim: interruptible.Everywhere else, headless is decided at launch and a human can neversee the session at any price. In hwatu it's a window property,switchable live, in both directions.

The speed follows from the same design decision: hwatu is a warmdaemon, not a library you launch. The engine, the GPU context, thecompiled adblock ruleset, and a prewarmed WebView outlive everytask, so a check starts from a hot pipeline instead of a coldprocess. Playwright is a library and cold by nature. Keeping itwarm is something you build (a server process, connectionmanagement, context pooling); hwatu ships warm as the default andthe only mode.

How hwatu compares

Legend: ✅ Yes / built-in · 🟡 Partial / limited · ❌ No

1 toHaveScreenshot compares against stored goldens: pass/fail fortest suites, not a score an agent can climb.

2 Standard practice is to disable animations or fast-forward to theend state to avoid flakes.

3 Raw CDP can query animation state, but there is no numericsummary 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 winscold start (190 vs 435 ms, paid once per boot) and memory; hwaturenders WebKit not Chromium (keep a Playwright matrix in CI forengine-specific bugs), and it is Linux-only today. Fullhead-to-head data and methodology:docs/benchmarks.md.

MIT licensed. Linux. WebKitGTK 6.