Give your AI agents eyes. Lens opens what you just built in a real browser, captures what actually renders, and hands back a deterministic, agent-ready report — no AI, no vision models, no guesswork.
lens check http://localhost:3000Lens completed: PASS
Report: .lens/runs/<timestamp>/lens-report.md
That's it. Point Lens at a local dev server and it tells you — with evidence — whether the page loads, renders, and behaves.
Lens produces artifacts you can read and show. A self-contained HTML report,
and — for executed flows — a walkthrough.html that pairs the recording with a
synchronized step timeline and a tamper-evident verdict.
 lens-report.html — verdict, severity counts, screenshots, color-coded findings. |
 walkthrough.html — recording + step timeline + run fingerprint (typed secrets stay redacted). |
Executed flows (lens flow --execute --record) drive the page for real — and
the recording shows a cursor gliding to each target and clicking it:
- Why Lens · Quick start · What you can do
- What it checks · How it works · Output
- Lens vs. other tools · Exit codes · Learn more
When an agent (or a person) builds a web app, the hard question is "does it actually work?" Lens answers it the same way every time:
- 🎯 Deterministic — every finding is backed by captured evidence. Same input, same report. No LLM judgment calls.
- 🏠 Local-first — only
localhost/127.0.0.1by default. External URLs need an explicit--allow-external. - 🤖 Agent-ready — emits a structured Agent Repair Brief and stable JSON (
schema_version: 1) an agent can act on directly. - 🔒 Secret-safe — tokens, JWTs, credentials, and sensitive params are redacted from every artifact and report.
- 👀 Observe, don't touch — opens a URL and watches. It never clicks, types, logs in, or submits forms unless you opt into a safety-gated flow.
Lens 1.0 is stable within its deterministic local-first scope: the core
contracts are intentionally small, documented, and tested. The repo is structured as a Kujo showcase: source
lives under src/, browser-only work is isolated in bridge/, examples are
copyable, and the test suite covers CLI parsing, safety rules, redaction,
reports, flows, visual checks, accessibility, integrations, and failure paths.
kujo --version
cd /path/to/lens/bridge && npm install && npx playwright install chromium
cd /path/to/lens
./lens check http://localhost:3000Prerequisites: the Kujo runtime, Node.js ≥ 18, and bash.
New to Lens? The Getting Started guide walks you from a clean machine to your first report and the test suite, step by step.
| Command | What it does |
|---|---|
lens check <url> |
Load a URL, capture evidence, run checks, write a report |
lens check <url> --check-links |
Also verify same-origin links (opt-in) |
lens check <url> --accessibility |
Add automated axe-core accessibility scanning |
lens check <url> --perf |
Capture opt-in performance evidence |
lens check <url> --crawl --max-depth 1 |
Run a bounded same-origin crawl |
lens check <url> --html |
Write a self-contained HTML report |
lens check <url> --browser firefox |
Run with another Playwright browser engine |
lens check <url> --spec spec.json |
Verify deterministic browser assertions |
lens check <url> --baseline / --compare-baseline |
Save / diff visual regression baselines |
lens flow flow.json --validate |
Check flow structure and safety without launching a browser |
lens flow flow.json --execute --record --walkthrough |
Run a safe flow and produce proof |
lens check <url> --json |
Print a machine-readable summary to stdout |
Run lens --help for the full flag list.
Every run looks for the failures that break a freshly-built page:
- 🚫 Page load failures, navigation errors, and timeouts
- 🐛 Console errors and warnings
- 🌐 Network failures (4xx / 5xx / dropped requests)
- 📄 Blank pages (multi-signal detection)
↔️ Horizontal overflow that breaks layout- 🖼️ Missing screenshots, plus optional link, accessibility, and visual-diff checks
Findings come with stable IDs (LENS-CONSOLE-001), a severity
(info < warning < error < critical), and a suggested repair task.
lens check <url>
│
├─ 1. Validate URL (localhost-safe by default)
├─ 2. Drive headless Chromium via a minimal Node/Playwright bridge
├─ 3. Capture evidence: screenshots, console, network, DOM
├─ 4. Run deterministic checks in pure Kujo
└─ 5. Write Markdown + JSON reports and an Agent Repair Brief
The bridge only does what Kujo can't do natively (drive a browser). Every decision — checks, findings, redaction, reports — happens in Kujo.
Each run writes a self-contained directory:
.lens/runs/<timestamp>/
├── lens-report.md # human-readable report
├── lens-report.json # stable JSON (schema v1)
├── metadata.json # timing, config, versions
├── console.json # redacted console messages
├── network.json # redacted network events
├── dom-summary.json # element counts & dimensions
└── screenshots/
├── desktop.png # 1440×900
└── mobile.png # 390×844
Reports are redacted by default. See Redaction & Privacy for what Lens redacts and how to review it.
| Code | Meaning |
|---|---|
0 |
No findings above the --fail-on threshold |
1 |
Findings at or above the threshold |
2 |
Invalid input (bad URL, blocked external URL) |
3 |
Browser/provider failure |
4 |
Artifact-write failure |
Lens overlaps with several tools but occupies a deliberately narrow niche: deterministic, local-first, agent-ready browser QA with zero AI.
| Lens | Lighthouse CI | Playwright Test | Percy / Chromatic | |
|---|---|---|---|---|
| Primary job | Evidence + repair report | Perf/quality scores | Assertion-based E2E tests | Visual snapshot review |
| Deterministic (no LLM) | ✅ | ✅ | ✅ | ✅ |
| Local-first, no account | ✅ | ✅ | ✅ | ❌ (hosted) |
| Zero test code to write | ✅ | ✅ | ❌ (you write specs) | ❌ |
| Agent-ready repair brief + stable JSON | ✅ | ❌ | ❌ | |
| Secret redaction across artifacts | ✅ | ❌ | ❌ | ❌ |
| Records a shareable "it passes" walkthrough | ✅ | ❌ | ||
| Accessibility (axe-core) | ✅ | ✅ | ❌ | |
| Performance metrics | ✅ (deep) | ❌ | ❌ |
Use Lighthouse for deep perf budgets and Playwright Test for rich assertion suites. Reach for Lens when an agent (or you) just built something and needs fast, deterministic, evidence-backed answer to "does it actually work?" — plus an artifact to prove it.
New here? Start with the Getting Started guide — install, setup, first run, reading the report, and tests, end to end.
The full reference covers every flag, the JSON schema, the safety model, Spec/Eval integration, flows, visual regression, and accessibility in depth.
- Getting started
- Flow authoring — task description → flow JSON (with an agent prompt)
- Examples — canonical, copyable
.lens.toml, flows, and specs - Enhancement checklist — where Lens is headed next
- Enterprise readiness next session — the next improvement list
- CLI reference
- Safe browser flows
- Visual regression
- Accessibility checks
- Redaction & privacy
No AI/LLM analysis. Not a general browser-automation tool. Not a security scanner. Not a crawler. Not a WCAG-compliance certifier. Lens is deliberately narrow: deterministic browser QA, done well.
kujo run tests/lens_tests.kujo # full test suite passes- Changelog
- Contributing — the build + verification gauntlet
- Enhancement checklist — the roadmap, task by task
- Enterprise readiness next session
MIT © Robert DeVore — see LICENSE.