jev-seo is a live SEO audit for any website, from one homepage URL. 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. Code scores and ranks every fix, and you get a designed PDF, an Excel action tracker and a Markdown report, all built from the same data.

It runs as a Claude Code skill (/jev-seo https://example.com) or from the command line. The standard mode needs no SEO data subscription and costs about a cent in Jev per site. An optional --full mode adds rankings, keywords and backlinks from DataForSEO for about 0.30 USD.

Start here: Example report · Skill workflow · How Jev is asked · How far to trust it · Method and formulas

A full audit of claude-seo.md, run with --full on 2026-09-22. Every file is in examples/claude-seo.md/: report.pdf · report.xlsx · report.md · digest.md · narrative.json.

PDF: how the audit was made, the scorecard and the priorities

PDF: search visibility from DataForSEO, filtered by Jev

PDF: how Jev reads the site

XLSX: the Actions sheet is the editable status tracker (rendered preview of the real workbook cells)

Markdown: renders on GitHub and in Obsidian, with charts

Live progress while it runs (lines from a real run)

Impact versus effort	Keywords worth winning	Where to invest

Python 3.10+. WeasyPrint needs the Pango text library: on Debian or Ubuntu sudo apt install libpango-1.0-0 libpangoft2-1.0-0, on macOS brew install pango, on Fedora it is usually present (WeasyPrint install notes).

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

Optional: pip install playwright && playwright install chromium renders pages whose content only appears after JavaScript runs; without it those pages are audited from their raw HTML. pdftoppm (poppler) is only used by the Claude Code skill to look at rendered pages.

Reports land in jev-seo-reports/<domain>-<stamp>/. The offline tests need no keys and spend nothing:

python -m unittest discover -s tests -v

In Claude Code, link the folder as a skill (ln -s "$PWD" ~/.claude/skills/jev-seo) and run /jev-seo https://example.com. The skill runs the audit in the background, relays progress, reads the digest, checks surprising findings, writes the narrative and renders the three reports.

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 audit https://example.com --full --reuse-dfs <dir>   # reuse DataForSEO data already collected
bin/jevseo rescore jev-seo-reports/<dir>                        # rebuild findings and scores offline, no spend

Both paid APIs sit behind hard caps (--jev-budget, default 0.25 USD; --dfs-budget, default 1.00 USD) checked before every request, and every call is in the report's cost ledger. Keys come from the environment or a .env file (see .env.example): TYPESAFE_API_KEY, optionally PAGESPEED_API_KEY (without it PageSpeed is often rate limited), and for --full DATAFORSEO_USERNAME and DATAFORSEO_PASSWORD. Without the TypeSafe key the audit still runs, marks the Jev sections as not assessed, and labels the score a partial audit.

Measured on 2026-09-22 and recorded in references/evaluation.md:

The blind judge is a separate model, not a human, so this shows Jev is consistent and reasonable, not that it is right. Answers outside the decisive band are flagged "to verify" in every format. Question wording and the decisiveness measure were chosen by A/B tests; the results are in references/judgments.md.

• Polite crawl: robots.txt and Crawl-delay, sitemap indexes, redirects recorded separately, host and HTTPS probes, soft 404 check, llms.txt, a private-network guard on every redirect hop.
• 52 rules across crawl and indexing, on-page, content, links, structured data (including properties Google requires for rich results), AI crawler access, performance and security.
• Jev: 13 page questions, 5 site questions, competing page pairs, and in --full mode keyword relevance, other-brand checks and the best page for each keyword. The homepage type is set by code, never asked.
• DataForSEO in --full mode: ranked keywords, estimated traffic, competitors, referring domains compared, keyword suggestions, ideas and gaps, live Google results with AI Overview citations, LLM mentions.
• PDF: cover, summary, plan, pipeline, scorecard, impact versus effort, site map, rankings, keyword opportunities, Jev cards, quality heatmap, where to invest, findings by area, page inventory, method, sources.
• XLSX: Actions tracker with dropdowns, Summary counting from it, Pages, raw Jev judgments with probabilities, Technical, Performance, Rankings, Opportunities, Competitors, SERPs, AI mentions, Charts, Method.
• Markdown with charts, Mermaid pies and a contents line.
• Narrative checks: unknown action IDs are refused; numbers not in the audit and mismatched effort bands are flagged.

This is an evidence tool, not a rank tracker or a replacement for Search Console. It does not measure traffic, revenue or rankings over time.

SKILL.md              Claude Code skill: workflow, options, rules
bin/jevseo            runs the package from any directory
jevseo/               crawl, parse, checks, jev, dfs, psi, score, cli
jevseo/report/        view model, charts, pdf, xlsx, md
jevseo/templates/     report HTML and CSS
references/           narrative contract, Jev question registry, evaluation, method
examples/             a complete example audit
docs/assets/          README images
tests/                offline tests, no network and no spend

Large sites are sampled at the page cap (60 by default) and the report says so. Jev thresholds are not yet tuned against human labels. PageSpeed lab scores vary between runs, and field data exists only for sites with enough Chrome traffic. DataForSEO volumes, difficulty and traffic are estimates. Rules marked heuristic are editorial conventions, not search engine requirements.

MIT. The bundled fonts in jevseo/fonts/ are Inter and JetBrains Mono under the SIL Open Font License (license texts alongside). Jev is a product of TypeSafe AI; DataForSEO and PageSpeed Insights are third-party services with their own terms.