Skip to content
Back to search

hwatu

Headless verification browser for AI coding agents: 35 ms one-call checks, pixel diffs, live human hand-off

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/hongnoul--hwatu/badge.svg)](/listings/hongnoul--hwatu)

HTML

<a href="/listings/hongnoul--hwatu"><img src="/api/listings/hongnoul--hwatu/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.

These steps run a script from the network that findsafeskills does not scan.

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

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

Then connect an agent:

hwatu setup             # detect Claude Code, Cursor, Jcode, or MCP

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 · 283 lines · 1 finding marked

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

  1. <div align="center">
  2. # hwatu
  3. [![Latest Release](https://badgen.net/github/release/hongnoul/hwatu?icon=github)](https://github.com/hongnoul/hwatu/releases)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
  5. [![CI](https://github.com/hongnoul/hwatu/actions/workflows/ci.yml/badge.svg)](https://github.com/hongnoul/hwatu/actions/workflows/ci.yml)
  6. **Headless UI verification for coding agents**
  7. <a href="https://github.com/hongnoul/hwatu/releases/download/readme-assets/demo-aiuc.mp4"><img src="https://github.com/hongnoul/hwatu/releases/download/readme-assets/demo-aiuc.webp" alt="An agent verifies aiuc.com with hwatu: one command returns pixel-match scores for four responsive viewports, then the live page pops into view for human hand-off" width="800"></a>
  8. </div>
  9. hwatu is a headless verification harness for coding agents: a warm
  10. WebKit daemon driven over CLI, MCP, or one JSON line per Unix-socket
  11. connection. Instead of "looks right to me", the agent gets **one-call
  12. verified page checks in ~35 ms**, **pixel-diff scores it can climb**,
  13. **animations as numbers**, and **headless windows that never steal
  14. focus**, at any parallelism. Jcode drives it natively as its `browser`
  15. backend. When a check needs a human (a CAPTCHA, a judgment call),
  16. `hwatu focus <id>` materializes the same live session as a real window.
  17. ## Documents
  18. - [Agent guide](docs/agents.md): protocol, primitives, verification loops
  19. - [Benchmarks](docs/benchmarks.md): every number, measured, with methodology
  20. - [Vision](VISION.md): durable product principles, native platform strategy
  21. - [Human guide](docs/human.md): hwatu as a tiling-WM browser, keybinds, hand-off
  22. - [Roadmap](docs/roadmap.md): portfolio priorities and product boundaries
  23. - [AI verification](docs/roadmaps/verification.md)
  24. - [Tiling-WM browser](docs/roadmaps/browser.md)
  25. - [Shared platform](docs/roadmaps/platform.md)
  26. - [macOS research](docs/research-macos-headless.md): measured WKWebView probes, competitor scan, and why macOS is verification-only
  27. - [Continuous improvement](docs/continuous-improvement.md): activation metric, feedback loop, weekly cadence
  28. - [Launch kit](docs/launch-kit.md): reusable copy, channels, and measurement plan
  29. ## Install
  30. ```bash
  31. curl -fsSL https://raw.githubusercontent.com/hongnoul/hwatu/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 41 on GitHub
  32. ```
  33. One static binary plus your distro's `webkitgtk-6.0` (the installer
  34. checks). On Arch: `yay -S hwatu`. From source: `cargo build --release`.
  35. Then connect an agent:
  36. ```sh
  37. hwatu setup # detect Claude Code, Cursor, Jcode, or MCP
  38. ```
  39. ## Verification, not vibes
  40. - **"Pixel-perfect" is a claim. `match_percent: 97.49` is a measurement.**
  41. - **One tool call per page check, ~35 ms. The same pass through warm-server Playwright is 5 calls and ~9x slower.**
  42. - **Headless by default. No window pops, no focus stolen, you keep typing.**
  43. - **One static binary + your distro's webkitgtk. No Node, no 170 MB Chromium download.**
  44. `hwatu setup` detects supported coding agents without changing their
  45. config. Choose a client explicitly:
  46. ```sh
  47. hwatu doctor
  48. hwatu setup --client claude --scope project --dry-run
  49. hwatu setup --client claude --scope project
  50. hwatu demo
  51. ```
  52. Setup is previewable (`--dry-run`), idempotent, and reversible
  53. (`--undo`). Manual MCP configuration is one portable entry:
  54. ```json
  55. { "mcpServers": { "hwatu": { "command": "hwatu", "args": ["mcp"] } } }
  56. ```
  57. Or skip MCP: every command is a short CLI call or one newline-delimited
  58. JSON line over a Unix socket.
  59. Connecting hwatu makes its tools available; a project instruction tells
  60. the agent when to use them. Add this to `AGENTS.md`, `CLAUDE.md`, or
  61. Cursor rules:
  62. ```markdown
  63. ## Frontend verification
  64. Use Hwatu after frontend changes. Exercise the affected user journey and
  65. verify its intended visible, navigational, or persisted result with `expect`.
  66. A successful click or clean console is not proof of success. Check `console`
  67. for additional JavaScript and request failures after verifying the outcome.
  68. ```
  69. Then make the task's proof concrete:
  70. ```text
  71. Implement display-name editing on /settings. Use Hwatu to enter “Test User,”
  72. save it, verify the visible success state, reload, confirm persistence, and
  73. report any console errors.
  74. ```
  75. The verification loop:
  76. ```sh
  77. hwatu --headless localhost:3000 # its window; you never see it
  78. hwatu --headless staging.example.com # the reference
  79. hwatu diff --id 2 --other 1 --heatmap /tmp/heat.png
  80. # {"match_percent":85.13,"regions":[{"x":0,"y":160,"w":2048,...}]}
  81. hwatu motion --id 1 # the reference's animations, as numbers
  82. # easing cubic-bezier(0.25,1,0.5,1), 300ms, marquee 29.78px/s ...
  83. # ...agent edits code...
  84. hwatu diff --id 2 --other 1
  85. # {"match_percent":97.49} # climbing beats guessing
  86. ```
  87. This loop took a clone of stripe.com's landing page from **85.1% to
  88. 98.8% pixel match**. Reproduce it: [scripts/demo/](scripts/demo/). A
  89. second real-agent scenario (four responsive viewport diffs, then live
  90. human hand-off) with evidence manifests:
  91. [scripts/demo-aiuc/](scripts/demo-aiuc/).
  92. A full verification pass (open, load, eval, screenshot, close) is
  93. **one command, one tool call, ~35 ms median**
  94. ([benchmarks](docs/benchmarks.md)):
  95. ```sh
  96. hwatu check localhost:5173 --eval 'document.title' --shot=/tmp/after.png
  97. # {"title":"My App","eval":"My App","shot":"/tmp/after.png",
  98. # "console":[...],"load_ms":13,"total_ms":35}
  99. ```
  100. For a repeatable repo-level contract that also owns the preflight, local dev
  101. server, responsive screenshots, source-staleness check, and evidence report:
  102. ```sh
  103. hwatu verify .hwatu/about.verify.json
  104. ```
  105. The same executor is exposed to MCP clients as `verify_ui`, so agent
  106. harnesses do not rebuild the orchestration loop. See the
  107. [agent guide](docs/agents.md#verification-jobs-one-contract-for-every-harness).
  108. Generated HTML in hand and no server? `hwatu render` is the same
  109. one-call pass with the markup as input: no temp file, no
  110. `python3 -m http.server`:
  111. ```sh
  112. echo '<h1>generated</h1>' | hwatu render --stdin --shot=/tmp/gen.png
  113. # {"rendered":true,"shot":"/tmp/gen.png","load_ms":5,"total_ms":28}
  114. # React to load, console, download, and window events without polling.
  115. hwatu watch --kinds load,console
  116. # {"event":"load","seq":1,"window_id":7,"data":{"state":"started",...}}
  117. ```
  118. MCP clients call `subscribe_events` for the same stream as
  119. `notifications/hwatu/event`. Full protocol and verification loops:
  120. [agent guide](docs/agents.md).
  121. Elsewhere, headless is decided at launch and a human can never see
  122. the session. In hwatu it is a window property, switchable live, in
  123. both directions: `hwatu focus <id>` promotes any headless session to
  124. a real window for the human, state intact.
  125. `challenge` is detection and hand-off only, by design: no solver
  126. APIs, no token injection, no fingerprint games.
  127. ## The hand-off destination
  128. The hand-off works because hwatu is also a real browser, built for
  129. tiling WMs. `hwatu <url>` opens a window like your terminal opens a
  130. shell (your WM is the tab bar, there is none in the window):
  131. mainstream keybinds (`ctrl+l`, `ctrl+f`, `ctrl+k` palette,
  132. rebindable), native ad blocking (~119k EasyList rules compiled into
  133. WebKit's content-extension engine, zero JS in the request path),
  134. Chromium-curve scrolling, and unified shortform controls. Every
  135. window shares the one warm daemon (~56 MB per extra window),
  136. suspends when unfocused, and crash-restores at its last URL. Honest
  137. gaps: no Widevine or passkeys in WebKitGTK. WM configs
  138. ([hyprland](examples/hyprland.conf), [sway](examples/sway.config),
  139. [niri](examples/niri.kdl)), keybinds, and setup:
  140. [docs/human.md](docs/human.md).
  141. <a href="https://github.com/hongnoul/hwatu/releases/download/readme-assets/demo-shortform.mp4"><img src="https://github.com/hongnoul/hwatu/releases/download/readme-assets/demo-shortform.webp" alt="hwatu as the hand-off destination: quarter-width window spawns and Chromium-curve scrolling in a tiling WM" width="800"></a>
  142. ## Features
  143. - [x] Headless / background / focused as a *per-window* property, switchable live
  144. - [x] Human hand-off: `hwatu focus <id>` drops the live session into your tiling WM
  145. - [x] Pixel-diff scoring: match percent + diff regions + heatmap (`diff`)
  146. - [x] Animations as numbers: duration, easing, velocity (`motion`)
  147. - [x] Deterministic animation frames: pin all animations at time t (`seek`)
  148. - [x] Page state as JSON, tokens not pixels (`snapshot`)
  149. - [x] Real input events with structured errors (`click` / `type` / `scroll` / `upload`)
  150. - [x] JS errors, console output, failed requests (`console`)
  151. - [x] Push event subscriptions as JSON lines or MCP notifications (`watch`)
  152. - [x] One-call page assertions with polling (`expect`)
  153. - [x] CAPTCHA / anti-bot detection with structured wait/resume (`challenge`)
  154. - [x] MCP server, plain CLI, and a 1-line JSON socket protocol
  155. - [x] A real browser as the hand-off destination: keybinds, media, ad blocking, crash restore
  156. ## Why not Playwright or chrome-devtools-mcp?
  157. Three ways to give an agent a browser:
  158. | | How it runs | What it costs the agent loop |
  159. |---|---|---|
  160. | **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 |
  161. | **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 |
  162. | **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 |
  163. hwatu keeps exactly what makes checks instant (engine, GPU context,
  164. compiled adblock, a prewarmed WebView) and nothing that serves a
  165. human *unless that human asked for a window*. That is why it idles
  166. warm without a tab bar, and why a kept-warm Playwright server driven
  167. the same way costs 341 ms per client to hwatu's 39
  168. ([benchmarks](docs/benchmarks.md)).
  169. The second difference is what comes back. Playwright and
  170. chrome-devtools-mcp are automation APIs: they let an agent *drive* a
  171. browser, then hand back raw screenshots and DOM to eyeball. hwatu is
  172. a *verification* browser: the measurement primitives (`check`,
  173. `diff`, `motion`, `expect`) are built in, a window costs 13 ms, and
  174. headless is a window property, not a launch mode.
  175. ## How hwatu compares
  176. **Legend:** ✅ Yes / built-in · 🟡 Partial / limited · ❌ No
  177. | Capability | Playwright | chrome-devtools-mcp | hwatu |
  178. | --- | :---: | :---: | :---: |
  179. | Verify pass (load + eval + screenshot), warm in-process | 82 ms | n/a | **35 ms** |
  180. | Verify pass as a warm *service* (fresh client per check) | 341 ms | n/a | **39 ms** |
  181. | Tool calls per verify pass | 5 | 5 | **1** |
  182. | Pixel-diff score + regions + heatmap | 🟡 1 | ❌ | ✅ |
  183. | Animations as numbers, pinned mid-flight | ❌ 2 | 🟡 3 | ✅ |
  184. | Headless ↔ headed on a *live* session | ❌ | ❌ | ✅ |
  185. | Human hand-off mid-session, state intact | ❌ | ❌ | ✅ |
  186. | No focus stealing at N parallel agents | 🟡 4 | 🟡 4 | ✅ |
  187. | CAPTCHA detection + structured wait/resume | ❌ | ❌ | ✅ |
  188. | No Node, no per-version browser download | ❌ | ❌ | ✅ |
  189. 1 `toHaveScreenshot` compares against stored goldens: pass/fail for
  190. test suites, not a score an agent can climb.
  191. 2 Standard practice is to disable animations or fast-forward to the
  192. end state to avoid flakes.
  193. 3 Raw CDP can query animation state, but there is no numeric
  194. summary of easing/velocity/keyframes.
  195. 4 Fine headless; every headed window pops and takes focus.
  196. > Comparison reflects each project at the time of writing;
  197. > corrections are welcome. Honest caveats: Playwright still wins
  198. > cold start (190 vs 435 ms, paid once per boot) and memory; hwatu
  199. > renders WebKit not Chromium (keep a Playwright matrix in CI for
  200. > engine-specific bugs), and it is Linux-only today. Full
  201. > head-to-head data and methodology:
  202. > [docs/benchmarks.md](docs/benchmarks.md).
  203. **What about Claude in Chrome?** Different category. Claude in
  204. Chrome is one agent product driving *your* Chrome through an
  205. extension, sharing your profile, tabs, and focus, callable by nothing
  206. else. hwatu is a client-agnostic daemon any agent calls over CLI/MCP,
  207. with its own warm WebKit engine, headless by default, and
  208. verification primitives built in. Use Claude in Chrome to let Claude
  209. browse alongside you; use hwatu when agents need cheap, repeated,
  210. measurable page checks.
  211. ## Feedback
  212. A successful check, a failed install, a missing keybind, and a site
  213. that broke are all useful signals. Share a two-minute
  214. [use report](https://github.com/hongnoul/hwatu/issues/new?template=use-report.yml)
  215. or [report a bug](https://github.com/hongnoul/hwatu/issues/new?template=bug-report.yml).
  216. ---
  217. MIT licensed. Linux. WebKitGTK 6.

Ratings and comments

Sign in to rate this skill.

Sign in

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