What it is
lensy checks live documentation pages and gives each one two scores out of 100. Coding agents is how well a coding agent can find and read the page. AI search is how well AI search engines can retrieve and cite it. It runs the same checks as the website. The Coding agents score is built on AFDocs, the open Agent-Friendly Documentation checks, plus one Lensy check for headings.
It checks exactly the pages you give it and doesn't crawl your site. It runs on your own machine or CI runner, so nothing about your pages is sent to Perseverance AI.
Install
You need Node 22 or newer.
npm install -g @perseverance-ai/lensy@next
lensy --versionTo run it once without installing:
npx @perseverance-ai/lensy@next check https://docs.example.com/guideThe tool is an early release, published under the next tag. For now it's also what npm install -g @perseverance-ai/lensy installs.
Check a page
lensy check https://docs.example.com/guideA bare hostname such as docs.example.com works too and gets https:// added. For one page, the terminal shows both scores, whether an honest AI agent can reach the page and how much of the page an agent receives. Then it lists what to fix first, ordered by the points each fix is worth, with one line on what to do. The points add up to each score: fix everything listed and both scores reach 100. A page takes a few seconds, or up to half a minute on a large site.
Example output, shortened:
https://vitepress.dev/guide/getting-started
Coding agents 87/100 AI search 95/100
Reachability: an honest AI agent can read this page (HTTP 200). robots.txt allows all 6 AI search bots.
What an agent receives: Markdown, 6,235 characters (about 1,559 tokens), fits in one fetch
Fix these first
1. Page points agents to llms.txt (HTML) −6 Coding agents
Add a visually-hidden element near the top of each page containing a link to your llms.txt.
2. JSON-LD −5 AI search
Add a JSON-LD block (for example TechArticle) with dateModified.
3. Page points agents to llms.txt (Markdown) −4 Coding agents
4. Markdown on request −3 Coding agents
Passed: 20 of 25 Coding agents checks, 5 of 6 AI search checks.Add --verbose to see every check instead: its id, its points, what it found and the full fix. Checks that come from AFDocs are marked AFDocs. AFDocs checks add up to more than 100 points, so the score scales them to 100, and the verbose view says so.
Colour is off when the output goes to a file or a pipe, when you pass --no-color, and when the NO_COLOR variable is set.
Check several pages
Give more than one URL:
lensy check https://docs.example.com/start https://docs.example.com/apiOr list them in a file, one URL per line. Blank lines and lines that start with # are ignored.
# docs to check
https://docs.example.com/start
https://docs.example.com/apilensy check --urls-file urls.txtWith several pages, the terminal shows one row per page with both scores, then the three most useful fixes for each page. The full detail goes in a report file. A URL listed twice is checked once.
Page Coding agents AI search Status
https://vitest.dev/guide/cli 83/100 68/100 ok
https://vitest.dev/guide/features 87/100 71/100 ok
https://vitest.dev/guide/ 87/100 68/100 okPages are checked two at a time. --concurrency takes a number from 1 to 5. There is no page limit. Above 15 pages, the tool prints the page count and a rough time before it starts.
Check a local build
Check your docs before you publish them: build the site, then point Lensy at the build folder. Lensy serves the folder on your machine for the length of the run and checks it like a published site. Nothing is sent anywhere else.
npx vitepress build docs
lensy check --dir docs/.vitepress/dist --site-url https://docs.example.com --all--site-url is your published docs address. Your build's sitemap, llms.txt and canonical links name that address, and Lensy matches them to the local files, so the result is what the published site will get. --all checks every page in the build. Without it, name pages by their path, such as /guide/getting-started, or leave them out to check the home page.
The build folder depends on your docs tool: docs/.vitepress/dist for VitePress, build for Docusaurus, site for MkDocs and dist for Astro Starlight. If your docs live under a path, such as VitePress base: '/docs/', include it in --site-url: https://example.com/docs.
Some checks depend on your web server or CDN, not your build, so a local check leaves them out and says so. Each score shows the points earned out of the points it could check:
https://docs.example.com/guide/getting-started
Coding agents 58 of 70 points checked AI search 77 of 100 points checked
Fix these first
1. Freshness declared −15 AI search
Set lastUpdated: true in the VitePress config.
2. Page points agents to llms.txt (HTML) −6 Coding agents
Not checked here (your web server or CDN decides these, so check the live site for them): Markdown
on request, Real 404s for missing pages, Redirects, Cache headers, Public without login, Bot
protection lets agents in.Fix something, rebuild and check again. With saving on, you see the change straight away:
Since today: Coding agents 58 → 58 AI search 77 → 89 (+12)Already running your docs tool's preview of the production build? Point Lensy at it instead: lensy check http://localhost:4173 --site-url https://docs.example.com --all, where --all reads the preview's sitemap. Use the preview command (vitepress preview, docusaurus serve), not the dev server, which can render pages differently.
Save a report
Add --html, --md or --json to save the full result. Use any of them together in one run.
lensy check https://docs.example.com/guide --html report.html --md report.md --json report.jsonThe HTML report is one file that opens offline: no scripts and no external links, with light and dark themes. The Markdown report is for coding agents. It starts with the scores and the tool version, then the checks in tables, then each fix as a checkbox, ordered by how many points it gains, so you can hand it to an agent as a to-do list. Both reports hold the same content in the same structure, called report version 1. The JSON file is for scripts and CI: each page has its scores, its fixes ordered by points lost, and the full check results. Use --json - to print only the JSON, for example to pipe it to jq. The folder you name must already exist. If it doesn't, the command stops before it checks anything.
Save and compare runs
Lensy can keep every run and compare each page with its last run, so you can see whether your docs got better or worse, what you fixed and what broke. The first time you run lensy check in a project, it asks:
Save Lensy results for this project in .lensy? Each run is compared with the last one, so you can see what changed. [Y/n]Answer y and Lensy creates a .lensy folder at the root of your project (the folder with .git, or the current folder outside a git project) and remembers the answer there. Answer n and nothing is created; Lensy remembers that in ~/.lensy/config.json and doesn't ask again. It only asks in a terminal. In CI, in a script, or with --json -, it never asks, and saves only when told to.
From the next run on, each page shows what changed since its last saved run:
https://vitepress.dev/guide/getting-started
Coding agents 87/100 AI search 95/100
Since Nov 2 (6 days ago): Coding agents 80 → 87 (+7) AI search 95 → 95
Fixed: llms.txt existsNew: lists checks that passed last time and lose points now. With several pages, the summary table gets a Change column, such as +7 / 0 or first run.
The folder holds JSON for scripts and Markdown for people and coding agents:
.lensy/
├── config.json project settings
├── latest.md the last run, every page: hand it to a coding agent
├── history.md one row per page per run, newest first
└── pages/
└── docs.example.com/guide/start/
├── page.json which URL this folder is for
├── latest.json the newest result for this page
├── latest.md the report for this page
└── runs/2026-11-08T183012Z.json one file per runLensy keeps the newest 52 runs of each page. List the pages you check in .lensy/config.json, and lensy check with no URLs checks them all. Keep "save": true in that file so runs without a terminal, such as in CI, save too; if .lensy exists but a run doesn't save, Lensy says so.
{
"configVersion": 1,
"save": true,
"keep": 52,
"pages": ["https://docs.example.com/guide/start", "https://docs.example.com/api"]
}For one run, --save saves even if you answered no, --no-save skips saving and the question, and --save-dir saves in another folder. Saved results stay on your machine. Commit .lensy to share the history with your team.
Explain a check
lensy explain llms-txt-existsThis prints what the check measures, why it matters, how many points it is worth and the evidence behind it. Use any check id from a report or from --verbose. Ids are not case sensitive. They are the AFDocs names, such as llms-txt-exists and rendering-strategy, lensy-headings for Lensy's heading check, and S1 to S6 for AI search. C1 to C6 are the Coding agents checks Lensy uses only when AFDocs can't run.
Exit codes
0: every page was checked.2: the command was wrong. There was no URL, an option had a bad value, a--dirfolder had no built pages,.lensy/config.jsonhad a problem, or results couldn't be saved where asked. Nothing was fetched.3: at least one page couldn't be checked. It was unreachable, it wasn't an HTML page, or its bot protection refused the tool. The other pages still print.1: something unexpected failed, or the results of a run that was told to save couldn't be written. The message starts withlensy:orCouldn't save results.
Scores never change the exit code, so a failing check doesn't fail a CI job. A page that couldn't be checked does. If a site's bot protection refuses the tool, it doesn't retry as a browser. It says the page wasn't checked and points you to the audit on perseveranceai.com.
What it sends
Every request carries lensy-cli/<version> (+https://perseveranceai.com/bot). The Lensy checker page explains what Lensy fetches and how a site owner can allow it.
For each page the tool fetches the page itself, robots.txt, the sitemap, llms.txt, a sample of the pages llms.txt links to, the Markdown version of the page, and a few other URLs that the AFDocs checks need. That is usually 15 to 60 requests per page. They go from your machine to the sites you named, and nowhere else. Saved results are written only to your own disk.
--user-agent sends a different name, for example to test a rule on your own site. --timeout sets how long each request may take, in milliseconds, from 1000 to 120000.
What it can't do yet
- Check source files before you build.
- Check pages behind a login. The tool can't sign in, so it only checks public pages.
Requirements and help
You need Node 22 or newer and npm. There's no account, API key or setup. For live pages, Lensy needs network access to the sites you check and nothing else. A local build check sends nothing off your machine.
Tested on. Every pull request runs the full test suite on Linux, macOS and Windows with Node 22 and 24. By hand, on macOS with Node 22, 24 and 26, we checked live pages on VitePress, Docusaurus, Mintlify, GitBook, Read the Docs, MkDocs Material, Nextra, Starlight and others, and local builds from VitePress 1.6 (with and without a base path), Docusaurus 3.10, Astro Starlight 0.42 and MkDocs Material 9.8. Windows and Linux desktops are covered by the automated tests, not yet by hand.
Known issues being fixed: Astro's sitemap-index.xml and sitemaps under a base path aren't read yet, and a canonical link written without quotes, as Docusaurus minifies it, isn't detected. Each costs some AI search points it shouldn't.
Found a problem? Email hello@perseveranceai.com or use the contact page. Include lensy --version, node -v, your operating system, the command and its output; add LENSY_DEBUG=1 if it failed with an error. Never send tokens, internal hostnames or unpublished content. The command line tool is free to use under the Terms of Use.