Introduction
Lenses turns web pages into functions that return JSON. It runs them in your own Chrome, so a lens can read any page you are signed in to.
lens call hn/top -c git:github.com/notationlabs/lenses#main/examples{
"kind": "value",
"value": {
"stories": [
{
"title": "My YC app: Dropbox - Throw away your USB drive",
"score": "104 points",
"item_url": { "$lens": "@djgrant/hn/item", "params": { "id": "8863" } }
}
],
"next_page": { "$lens": "@djgrant/hn/top", "params": { "page": 2 } }
},
"resolver": "dom"
}item_url and next_page are not URLs. Each one names another lens and its parameters, so you follow links by making another call.
You can call a lens from the lens CLI, from TypeScript, from an AI agent over MCP, or through a GraphQL server.
A lens is a JSON file
examples/hn.top.json declares the page, the parameters, the result shape and how to read the data:
{
"name": "@djgrant/hn/top",
"url": "https://news.ycombinator.com/news?p={params.page}",
"params": { "page": { "type": "integer", "default": 1 } },
"returns": { "type": "object", "fields": { "stories": { "type": "array", "items": { "title": "string", … } } } },
"resolve": [{ "kind": "dom", "item": ".athing", "fields": { "title": { "selector": ".titleline > a" }, … } }]
}The client checks every result against returns. If the page changes and the data no longer fits, you get an error that lists the mismatches instead of bad data.
Signed-in pages
claude/usage reads your plan and usage limits from claude.ai. Lenses does not ask for your password, cookies or an API token. A background process called the broker makes the requests from inside your Chrome, so claude.ai sees your normal session. A lens file cannot read your cookies.
When you are signed out, the call returns an outcome instead of a value:
{
"kind": "outcome",
"name": "needs_auth",
"value": { "$lens": "@djgrant/claude/login" },
"hint": "Ask the user to sign in to claude.ai in the open tab, then retry this call."
}The lens author named this state in advance, so your code can handle it instead of parsing an error.
Fallbacks when a site changes
A lens can list several ways to get its data, cheapest first. Lenses tries the next one only if the earlier ones fail. claude/usage has four:
"resolve": [
{ "kind": "http", "credentials": true, … }, // ← call claude.ai's API with your cookies; no tab opens
{ "kind": "intercept", … }, // ← open the page and read the JSON it fetches
{ "kind": "dom", … }, // ← read the rendered HTML with CSS selectors
{ "kind": "llm", "prompt": "…" } // ← hand the page text to the caller's AI model
]While claude.ai's API works, the call never opens a tab. If the API changes, the call still works through the page. Resolvers describes each kind.
Next steps
- Installation connects Lenses to Chrome.
- Quick Start walks through your first calls.
- Writing a Lens builds
hn/topfrom scratch.