AgentLens gives AI coding agents a semantic understanding of web pages. Not raw HTML. Not flat element lists. Structured components with suggested actions. NEW
Install
npm install agentlens
The Problem
AI agents dump the entire DOM into their context window. A single page.content() call burns 50,000 tokens on noise. AgentLens returns ~120 tokens of signal.
| page.content() — what agents do now | agent.digest() — with AgentLens |
<div class="sc-bdnxRM jKEGSp">
<div class="sc-gsTCUz kJHfbo">
<div class="sc-dlfnbm iISzev">
<span data-reactid=".0.1">
<div class="css-1dbjc4n">
<div class="css-901oao">
Login
</div>
</div>
</span>
<input class="sc-kgoBCf"
...
~50,000 tokens of noise
|
Page: My App (myapp.com/login) Status: ready Suggested: fill 2 required fields [nav] Header: Home, About, Pricing [form] Login: 0/2 filled Email *: empty Password *: empty submit: "Sign In" [hero] Welcome: CTA "Get Started" Actions: fill | submit | navigate ~120 tokens of signal
|
Features
| Feature | Description |
|---|---|
| Semantic Digest | Pages as forms, navs, modals — not flat element lists |
| Intent Actions | "submit form", "log in with" — not "click button" |
| Delta Tracking | Only what changed since last check. "[no change]" = 3 tokens. |
| Smart Waiting | Watches spinners, network, DOM — not setTimeout |
| Blocker Detection | Auto-detects and dismisses modals, cookie banners, overlays |
| Context Budget | Set a token limit. Output auto-compresses to fit. |
| A11y Audit | Lightweight accessibility check — missing labels, heading hierarchy |
| Snapshot Testing | Regression test visible state against saved baselines |
Usage
Navigate + understand:
import { AgentPage } from "agentlens/agent";
const agent = new AgentPage(page);
const digest = await agent.goto("https://myapp.com");
// digest.text -> compact page model
// digest.tokens -> 127
// digest.suggestedAction -> "fill 2 required fields"
Act with intent:
await agent.do("log in with user@test.com / secret123");
// finds login form, fills email + password, clicks submit,
// waits for navigation — all in one call
await agent.do("navigate to Pricing");
await agent.do("search for enterprise plan");
await agent.do("dismiss blockers");
Track what changed:
const delta = await agent.whatChanged(); // "Navigated -> /dashboard // + [nav] Sidebar: Dashboard, Settings // - [form] Login // Suggested: click 'View Tasks'" // delta.tokens -> 42
API Reference
| Method | What it does |
|---|---|
| agent.digest() | Semantic page model — components, status, suggested actions |
| agent.do(intent) | Execute high-level intent — returns result + page delta |
| agent.whatChanged() | Delta since last observation — only what's new |
| agent.waitUntilReady() | Smart wait — watches spinners, network, DOM stability |
| agent.dismissBlockers() | Auto-close modals, cookie banners, overlays |
| agent.goto(url) | Navigate + wait + digest in one call |
| agent.screenshot(label) | Viewport screenshot + observation log entry |
Supported Intents
"submit form"/"submit Login""navigate to Pricing""log in with user@test.com / password""search for [query]""fill form with {email: a@b.com, name: John}""dismiss blockers""wait until ready""scroll to [component]""go back"
Package Exports
| Import Path | What You Get |
|---|---|
| agentlens/agent | AgentPage class — digest, intents, deltas |
| agentlens | observe, act, getVisibleState, uxReport — lower-level API |
| agentlens/fixture | Test fixture with { lens } |
| agentlens/reporter | Compact test failure reporter — no trace/DOM inlining |
CLI
$ agentlens init # scaffold config + example test $ agentlens doctor --fix # auto-patch your test config $ agentlens clean # clear observation log $ agentlens summarize # regenerate markdown report $ agentlens diff a.json b # compare two observation logs $ agentlens ci # generate GitHub Actions workflow
Agent Instructions
Add this to your AI agent's system prompt or CLAUDE.md:
When inspecting web pages, use agentlens:
- import { AgentPage } from "agentlens/agent"
- agent.digest() for compact page understanding (< 500 tokens)
- agent.do(intent) for high-level actions
- agent.whatChanged() for delta-only updates
- Never call page.content()