jev-seo README

The project's README from github.com/AgriciDaniel/jev-seo. As one markdown file: README.md.

jev-seo

version checks license python jev

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.

Cover, executive summary and plan of a jev-seo PDF report

Why it is useful

What you get Why it matters
A live crawl, not a template robots.txt, sitemaps, redirects, broken links, canonicals, structured data and JavaScript-only pages, checked on the real site in about a minute.
Meaning, judged by Jev 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.
Ranked, explained fixes Every action has an ID, priority, impact, effort, evidence, a fix and an official source. Heuristics are labelled as heuristics.
Honest numbers Missing data stays missing. Scores rank work; they never predict rankings or traffic. The written summary is checked against the audit before it renders.
Three formats, one source PDF for the client, XLSX to track the work, Markdown for GitHub and Obsidian, all from one audit.json.

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

See the output

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

Pipeline, scorecard and priority pages

PDF: search visibility from DataForSEO, filtered by Jev

Rankings, keyword opportunities and site structure pages

PDF: how Jev reads the site

Jev judgment cards, quality heatmap and where to invest

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

Actions sheet of the jev-seo workbook

Markdown: renders on GitHub and in Obsidian, with charts

Markdown report rendered

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

jevseo progress output

Impact versus effort Keywords worth winning Where to invest
Impact versus effort Keyword opportunities Where to invest

Try it

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

What runs where, and what it costs

How a jev-seo audit runs

Part Where it runs Cost
Crawl, rules, scoring, charts, PDF, XLSX, MD Your machine Free
JavaScript rendering for script-only pages Local headless Chromium (Playwright, optional) Free
Core Web Vitals and Lighthouse Google PageSpeed Insights API Free
Page, site and keyword judgments TypeSafe Jev API 0.042 USD per million input tokens; about 0.00015 USD per page
Rankings, keywords, competitors, backlinks, live SERPs, AI mentions (--full) DataForSEO API Reported per call; about 0.30 USD per site

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.

How far to trust it

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

Check Result
Rule and crawl facts, re-fetched independently from the live site All verified; word counts within 5%
DataForSEO internal consistency (keyword counts, position buckets, traffic sum, referring domains) Exact
PageSpeed, fresh independent run Identical scores and field values
Jev repeatability, same 59 pages twice Scores moved 0.03 or less on average; confident page types agreed 44/44
Jev against a blind second judge, answers Jev marks decisive Helpfulness and specificity 28/29, opens with the point 23/23, next step 16/16, keyword relevance 27/30

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.

What works

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.

Layout

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

Limits

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.

License

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.

jev-seo (AgriciDaniel/jev-seo)

Searching Database…

654 ·GitHub
Jev-seo
What is this?jev-seo is a live SEO auditor that crawls a site from one homepage URL, 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, producing a PDF, an XLSX action tracker and a Markdown report from the same audit data.
Is this a standalone CLI tool or only a Claude Code skill?Both: it runs as a regular Python command-line tool and also as a Claude Code skill (/jev-seo) that drives the same audit in the background and relays progress.
How do I run my first audit?Install Python 3.10+ and the Pango library WeasyPrint needs (apt install on Debian/Ubuntu, brew install pango on macOS), then run it from the command line, or link it as a Claude Code skill with 'ln -s "$PWD" ~/.claude/skills/jev-seo' and run '/jev-seo'. Reports land in jev-seo-reports/.
Do I need an API key for the Jev-judged parts?Yes, a TYPESAFEAPIKEY is needed for Jev's page and site judgments (about $0.00015/page); PAGESPEEDAPIKEY is optional for Core Web Vitals, and DATAFORSEOUSERNAME/PASSWORD are only required for the paid --full mode. Without the TypeSafe key the audit still runs but marks those sections unassessed.
Does it audit the whole site no matter how big it is?No, large sites are sampled at a page cap of 60 pages by default and the report states when sampling happened; PageSpeed lab scores can vary between runs, and Jev's scoring thresholds haven't yet been tuned against human labels.
Does it work on Windows, or just Linux and macOS?Install instructions only cover Debian/Ubuntu, Fedora and macOS (via apt or brew for the Pango library); Windows isn't mentioned in the setup steps.
What's actually in the three report formats?The PDF has a cover, summary, scorecard, impact-versus-effort chart and priorities for clients; the XLSX has an editable Actions tracker with dropdowns plus raw Jev judgments and probabilities; the Markdown version renders with Mermaid charts on GitHub or in Obsidian. All three come from the same audit.json.
How reliable are Jev's judgments?Repeated runs on the same 59 pages moved scores by 0.03 or less on average and agreed on confident page types 44 out of 44 times, and a separate blind model judge agreed with Jev's decisive answers on most checks, though this shows consistency, not proven correctness.
What does --full mode add?The --full flag pulls rankings, keywords, competitors, referring domains, live SERPs and AI-mentions from the DataForSEO API for about $0.30 per site, on top of the free crawl and ~$0.01 Jev-only standard audit.
What kind of checks does the free crawl cover?It politely crawls robots.txt and sitemaps, records redirects and host/HTTPS probes, checks for soft 404s and llms.txt, and runs 52 rules across indexing, on-page content, links, structured data, AI crawler access, performance and security.
What are similar projects?seo-monster, geo-seo-claude, rankme.fast, qiaomu-anything-to-notebooklm, open-seo-mcp-skills, seo-landing, SenseNova-Skills, new-term-radar
Which topics is it in?core-web-vitals, seo-audit, seo-optimization, seo-tools, web-crawler, xlsx, excel, charts, analytics, google, web-scraping, skill
Creator
AgriciDaniel
Size
6.5 MB
Stars
654
Updated
CommitSep 22
Age
26d
Commits · 90 Days