jev-seo: an SEO audit that asks a typed model for judgments

What the tool actually does in one minute of crawling

The project describes itself as a live SEO audit for any website from one homepage URL, judged by Jev. It crawls the site, checks it against 52 rules tied to Google Search Central, measures Core Web Vitals, and asks Jev, TypeSafe's System One model, typed questions about every page. The description also promises that it scores and ranks every fix, and that you get a designed PDF, an Excel action tracker and a Markdown report, all built from the same data. The primary language is Python, the licence is MIT, the version is 0.1.1, the default branch is main, the last push was on 2026-09-22, and the repository publishes no GitHub releases. The most distinctive claim is the second one, the judgment by Jev, and the README spends a lot of space qualifying exactly what that judgment is and is not.

bin/jevseo run https://example.com             # audit and render with an automatic summary

That single command audits the site and renders the report with an automatic summary.

Why a typed model instead of a checklist

The README's table of what you get makes the case for the model in two rows. A live crawl, not a template, means robots.txt, sitemaps, redirects, broken links, canonicals, structured data and JavaScript-only pages are all checked on the real site in about a minute. Meaning, judged by Jev, means page type, search intent, importance, helpfulness, specificity, trust, citability, title and meta fit, and pages competing for the same searches, each a typed answer with its probabilities kept. So the audit asks a System One model structured questions rather than inferring intent from markup patterns, and the answers arrive with the probabilities attached, which is what makes them auditable. The repository documents this separately in references/judgments.md for how Jev is asked and references/evaluation.md for how far to trust it, and the model itself is versioned in a badge, judged by Jev 1.13.0.

Ranked fixes, with evidence and an honest label

The output design is where this project differs from a script that prints a list of warnings. Every action has an ID, a priority, an impact, an effort, evidence, a fix and an official source, and the README says explicitly that heuristics are labelled as heuristics. That single rule is doing a lot of work, because a rule that fires on a heuristic and a rule that fires on a Google Search Central guideline look identical in a raw list. The scoring section is also deliberately modest. The README says missing data stays missing, that scores rank work but never predict rankings or traffic, and that the written summary is checked against the audit before it renders. That last point is a small but meaningful design decision, because a natural language summary is exactly where a report tends to drift from its data, and the tool verifies the summary against the audit rather than trusting the generator.

One dataset, three report formats

The outputs come from a single audit.json, and the README explains the reasoning in one row. The PDF is for the client, the XLSX is to track the work, and the Markdown is for GitHub and Obsidian. The example output section shows the pieces of a real run, with a full audit of claude-seo.md run with the --full flag on 2026-09-22, and the files are in examples/claude-seo.md/: report.pdf, report.xlsx, report.md, digest.md and narrative.json. The XLSX has a specific role, the Actions sheet is the editable status tracker. The Markdown is described as rendering on GitHub and in Obsidian, with charts. There is also a live progress output while the tool runs, which the README shows from a real run, and the summary and narrative appear to be produced alongside the deterministic findings rather than instead of them.

Installing it and running your first audit

The requirements are Python 3.10 and WeasyPrint, which needs the Pango text library. On Debian or Ubuntu that is the libpango and libpangoft2 packages installed with apt, on macOS it is brew install pango, and on Fedora it is usually already present. Then the clone and the virtual environment.

git clone https://github.com/AgriciDaniel/jev-seo.git
cd jev-seo
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                           # add TYPESAFE_API_KEY (optional keys are listed inside)
bin/jevseo doctor                              # dependencies and keys, never prints values
bin/jevseo run https://example.com             # audit and render with an automatic summary

The doctor command is worth noting: it reports dependencies and keys without ever printing the values. The .env file needs TYPESAFE_API_KEY for the standard audit, with PAGESPEED_API_KEY and the DataForSEO credentials optional. Reports land in a directory named jev-seo-reports/<domain>-<stamp>/. The offline tests need no keys and spend nothing.

The command surface, and what the optional extras cost

The CLI separates the stages so you can re-run parts of it. The audit command crawls, applies the rules, calls Jev and PageSpeed to produce audit.json and digest.md, and the render command turns a report directory into report.pdf, report.xlsx and report.md. Adding the --full flag pulls in DataForSEO for rankings, keywords and backlinks at about 0.30 USD per site, and a --reuse-dfs option reuses DataForSEO data you have already collected. There is also a rescore command that rebuilds findings and scores offline with no spend, which is the command to reach for when you want to change a threshold without paying again. The README states the standard mode needs no SEO data subscription and costs about a cent in Jev per site.

bin/jevseo audit https://example.com                            # crawl, rules, Jev, PageSpeed -> audit.json + digest.md
bin/jevseo render jev-seo-reports/<dir>                         # -> report.pdf, report.xlsx, report.md
bin/jevseo audit https://example.com --full                     # add DataForSEO (paid per call)
bin/jevseo rescore jev-seo-reports/<dir>                        # rebuild findings and scores offline, no spend

Running it as a Claude Code skill is the other route, with the folder linked as a skill and the command run inside the chat, where the skill runs the audit in the background, relays progress, reads the digest, checks surprising findings, writes the narrative and renders the three reports.

The limits, and what it is not

Three boundaries are worth stating before you adopt it. The first is that a full audit is not free in a strict sense, because the standard mode still costs about a cent in Jev per site, and the optional mode is paid per DataForSEO call, so a crawl of a large site with --full is a real bill. The second is the JavaScript rendering gap. Playwright is an optional extra, and the README is plain that without it, pages whose content only appears after JavaScript runs are audited from their raw HTML, which for a single page application means you are auditing the shell rather than the content. The third is the boundary of what a score means. The README is unusually careful to say the scores rank work and never predict rankings or traffic, so a jev-seo report is an audit and a prioritisation aid, not a forecast. The alternative to weigh is a conventional crawler plus a checklist, which costs less and produces less, or a commercial SEO platform, which costs more and produces a black box. The distinctive middle position here is a report that is readable by a human, diffable in version control and honest about which of its findings are heuristics.

Editorial conclusion

Adopt jev-seo if you want a repeatable SEO audit for a client or a site that produces the same three artefacts every time, a PDF for the client, an XLSX tracker and a Markdown report for the repository. Do not adopt it expecting a ranking prediction, since the README is explicit that the scores rank work and never predict rankings or traffic. Before you run it, read references/evaluation.md for how far to trust the output, decide whether the optional DataForSEO spend is worth it for your use case, and check that WeasyPrint's Pango dependency is available on your machine.

Frequently asked questions

Official sources

1. AgriciDaniel/jev-seo on GitHub
2. Issues
3. License: MIT
4. README