jev-seo

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.

Why it is useful

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

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)

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

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: