Run a full SEO audit from your terminal: hands-on with Claude SEO, the 22,000-star Claude Code plugin

Your SEO audit should end with a plan, not a pile of warnings. Claude SEO is a free plugin for Claude Code that sends 19 specialist agents across a site in parallel and returns a scored, prioritised action plan — and this guide installs it, sets up its runtime, and runs its tools, with every output shown as the run produced it.

• Who: AgriciDaniel/claude-seo on GitHub.
• What: a Claude Code plugin for full-site SEO audits: 26 sub-skills, 19 specialist agents, 60 Python tools behind one launcher, and a 0–100 health score with a prioritised action plan.
• When: created 7 February 2026; 22,543 stars and 3,088 forks at the time of writing, with 1,469 stars gained in 24 hours on 26 October 2026 per the GitNova tracker.
• Requirements: Claude Code 1.0.33 or newer; Python 3.11 to 3.14; Git for the manual route. No API keys for the core audit.
• Licence: MIT.
• Verified: plugin manifest counts match the cloned tree (26 skills, 19 agents, v2.5.0); manual install landed the same tree in an isolated home; doctor reported setup-required before setup; content-quality scorer returned 65 with thin-content flags on a test page; schema generator emitted valid ProfilePage JSON-LD — all through the documented launcher path once the runtime was ready.

Most SEO audits end the same way: a crawler dumps a thousand warnings, and a human still has to decide what matters. Claude SEO takes the opposite approach. It is a free, open-source plugin for Claude Code that turns the audit into a conversation: 19 specialist agents check a site in parallel, score what they find, and hand back a prioritised action plan instead of a pile of warnings. It is having a breakout week — 22,543 stars on GitHub, 3,088 forks, and 1,469 stars gained in a single day on 26 October 2026, according to the GitNova tracker — and this guide installs it, sets up its runtime, and runs its deterministic tools, with every output shown as the run produced it.

One boundary up front, because it shapes everything below. Claude SEO is a plugin for Claude Code, and the full audit is an agent run: it needs a Claude Code plan, and its own README says five of its agents run on Opus with the rest on Sonnet. This guide verifies everything that can be verified without that plan — the install, the runtime setup, the readiness check, and the offline tools — and it says plainly, in its own section, what it did not run. If you have Claude Code, the last step is yours to run; if you do not, the first three steps still leave you with a working, inspectable tool.

What you'll need

• Claude Code version 1.0.33 or newer, and a Claude Code plan if you want to run the full agent audit. The plugin itself is free and MIT-licensed, with no per-site pricing and no usage limits.
• Python 3.11 to 3.14. The plugin's launcher enforces that range itself; the sandbox used here ran Python 3.12.
• Git, for the manual install path. The plugin path needs no Git.
• No API keys for the core audit. Optional Google data (PageSpeed Insights, Chrome UX Report, Search Console, Analytics 4) connects later with /seo google setup, using keys you create; paid extensions such as DataForSEO need their own accounts.
• About 30 minutes. The runtime setup downloads a Python environment and, unless you skip it, a headless Chromium build, so it is the slowest step in this guide.

Step 1: Install Claude SEO

There are two supported routes, and they land in different places. The plugin route is the one the project recommends, and it is three commands inside Claude Code:

/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
/seo setup

The manual route clones the repository and runs its installer, which copies the skills, agents, schema templates, data files, and scripts into ~/.claude/skills/ and ~/.claude/agents/, then runs the same setup. For macOS and Linux:

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/install.sh

Verified here: a shallow clone of the repository (412 commits, default branch main) and the installer's file layout were checked against the plugin manifest. The manifest (.claude-plugin/plugin.json) declares version 2.5.0, an MIT licence, 26 sub-skills and 19 sub-agents, and the cloned tree matches those counts exactly: 26 directories under skills/ and 19 files under agents/. A manual install into an isolated home directory landed the same tree — skills including seo, seo-audit, seo-technical, seo-content, seo-schema, seo-geo, and seo-local — confirming the installer copies what it claims to copy. The installer's final step is the runtime setup from Step 2, so a manual install takes as long as that setup does; do not mistake a long install for a hung one.

Two details worth knowing before you choose. First, the project ships two versions of the plugin: the public MIT version used here, and a private early-access version for members of the author's community; the commands above install the public one. Second, the manual installer notes that hook enforcement requires the plugin install — a manual copy of hook files is best-effort. If you use Claude Code, take the plugin route.

Step 2: Set up the runtime, then check it

Claude SEO does not run its Python tools with your system interpreter. It ships a launcher, scripts/claude-seo, which builds and uses an isolated Python environment, and the project's own agent instructions are explicit: run bundled tools through the launcher, never with a bare interpreter. The first run therefore has two commands, and the order matters — the launcher refuses to run tools until setup has completed:

./scripts/claude-seo setup --skip-browser
./scripts/claude-seo doctor

Before setup, doctor reports the state plainly:

Runtime: setup required
Install mode: manual
Python: 3.12
Chromium: not installed
Reason: managed environment is missing

The --skip-browser flag is the sandbox-friendly choice: it builds the Python environment but skips the Chromium download, so rendered-page features (JavaScript-heavy pages, screenshots) stay unavailable until you run setup again without the flag. On a normal machine, run setup without the flag and let it fetch Chromium; the README says setup installs the headless browser for you.

After setup, doctor reports the change:

Runtime: ready
Install mode: override
Python: 3.12
Chromium: not installed

The "override" install mode is this guide's sandbox talking: the runtime was built with CLAUDE_SEO_DATA_DIR pointed outside the home directory, because the sandbox's home disk quota tripped during the default install. On your machine, without that override, the mode line will name your install type, and the line that matters — Runtime: ready — is the same. Chromium: not installed is the expected price of --skip-browser: run setup again without the flag to enable rendered-page features.

A note on time, earned the hard way: setup failed twice in this guide's sandbox before it succeeded — first the small temporary filesystem filled up while pip unpacked the project's dependency list (which includes matplotlib, numpy, weasyprint, and the Google API clients for the reporting tools), then the home disk quota tripped mid-install. The successful run moved both the data directory (CLAUDE_SEO_DATA_DIR) and the temporary directory outside home, and the finished runtime is 741 MB. If your setup fails with "No space left on device" or "Disk quota exceeded", check where your temporary directory and data directory live before blaming the installer — and budget a slow download: the dependency list is large.

Step 3: Run the deterministic tools through the launcher

With the runtime ready, the canonical form for every bundled tool is ./scripts/claude-seo run <script> [args]. Four offline tools run anywhere, need no keys, and show what the plugin's machinery actually does.

First, score a page's content quality. The scorer rates a page against search-quality-rater-style criteria and exits non-zero when the score falls below its threshold (default 60). Against a deliberately thin test page — one heading and one short paragraph about local search — it returned:

{
  "filler_score": 0,
  "ai_pattern_score": 0,
  "information_density": 0.0,
  "repetition_score": 2,
  "overall_quality": 65,
  "flags": ["low-density", "thin-content"],
  "tokens": 51,
  "unique_tokens": 37
}

The verdict is honest rather than flattering: the page passes the default threshold at 65, but the flags name exactly what is wrong with it — low density, thin content. That is the shape of a useful check: a number plus the reason for it.

Second, generate structured data. The schema generator emits Schema.org JSON-LD for a handful of high-leverage types. Asking it for a profile page produced valid, paste-ready output:

{
  "@context": "https://schema.org",
  "@type": "ProfilePage",
  "mainEntity": {
    "@type": "Person",
    "name": "Ada Lovelace",
    "url": "https://example.com/ada"
  },
  "url": "https://example.com/ada"
}

Add --script-tag and the same output comes wrapped in a <script type="application/ld+json"> tag, ready to paste into a page. The generator covers reservation, order, discussion, and profile types — a deliberately small set, which is the point: these are the types the project considers worth generating rather than hand-writing.

The same test page run through the HTML parser shows what a single-page check extracts before any agent judges it:

{
  "title": "Test page about local search",
  "meta_description": null,
  "h1": ["How local search works"],
  "word_count": 39,
  "schema": [],
  "open_graph": {},
  "hreflang": []
}

Title, headings, word count, schema blocks, Open Graph, and hreflang — the raw material the content and technical agents reason over, available as one command.

Third, check that the skills themselves are portable. The project authors its skills to a portable subset of the Claude Code skill spec so other harnesses (Cursor, Gemini CLI, Codex, Cline, Aider) can load them, and it ships a checker for exactly that:

./scripts/claude-seo run portability_check.py

Portability lint: 35 SKILL.md files checked
  errors:   0
  warnings: 0
  info:     0

Thirty-five skill files — the 26 core skills plus the extension skills — pass with zero errors, zero warnings, and exit code 0. That is the check to run before trusting a skill in a harness other than Claude Code.

One more check belongs in this step, because it guards the step after it. The plugin's fetch tools are deliberately SSRF-safe: they validate URLs and refuse addresses that resolve to non-public ranges. In this guide's sandbox, that guard refused https://example.com/ outright — "DNS rebinding refused: example.com resolves to non-public IP" — because the sandbox's DNS resolves public hostnames to its own egress range. That is a sandbox artifact, not a product defect, and it is the guard doing its job. On a normal network the same tools fetch and parse pages as documented. Do not disable the guard to work around a sandbox.

Step 4: Run your first audit (in Claude Code)

This is the step that needs Claude Code, and it is the reason the plugin exists. Start Claude Code, then:

claude
/seo audit https://example.com
/seo page https://example.com/pricing
/seo geo https://example.com
/seo schema https://example.com
/seo local https://example.com

The full audit follows a fixed pipeline, documented in the seo-audit skill rather than improvised per run. It renders the homepage, detects the business type (SaaS, local, e-commerce, publisher, or agency) from homepage signals, then crawls the site — up to 500 pages, respecting robots.txt, five concurrent requests, one second between requests — and fans out to the specialist agents: technical, content, schema, sitemap, performance, visual, AI-search (GEO), agent-readiness, and, when the signals call for them, local, maps, Google-data, backlinks, cluster, experience, drift, and e-commerce agents. The findings aggregate into an SEO Health Score from 0 to 100, and the artifacts land under {domain}-audit/: FULL-AUDIT-REPORT.md, ACTION-PLAN.md with recommendations ordered Critical, High, Medium, Low, audit-data.json as a structured envelope, per-category findings, and screenshots when the browser is available. A PDF report can be generated from the envelope afterwards with the Google-report tool.

The single-page and specialist commands are the audit broken into pieces you can run on their own. /seo page goes deep on one URL. /seo geo scores how quotable your pages are for AI answers — whether AI crawlers can reach them, whether an llms.txt exists, and how the brand shows up on Wikipedia, Reddit, YouTube, and LinkedIn. /seo schema detects, validates, and generates markup. /seo local covers the local pack: business-profile signals, name-address-phone consistency, reviews, and local schema. And /seo drift baseline followed later by /seo drift compare turns a one-off audit into monitoring: capture a baseline, then measure what changed.

When to use Claude SEO vs alternatives

• Use Claude SEO when the audit needs judgment, not just a crawl. A crawler finds the broken links; the agents explain which findings matter, in what order, and how you will know a fix worked. The AI-search coverage — GEO scoring, agent readiness, llms.txt — is the part traditional tools are still catching up on.
• Use a dedicated crawler when you need depth and speed. The project's own FAQ concedes this: tools like Screaming Frog crawl faster and deeper, and large SEO suites have their own backlink databases. Claude SEO caps its crawl at 500 pages and one second between requests. For a 50,000-page site, crawl first with a crawler, then audit the important pages here.
• Use a hosted SEO suite when you need its proprietary data. Backlink databases, keyword indexes, and rank trackers are not things a local plugin replicates. Claude SEO's free backlink sources are Moz, Bing, and Common Crawl; the paid DataForSEO extension is a separate account.
• Use a single-purpose skill when the job is narrower. A design skill polishes a page's look; a content skill drafts copy. Claude SEO is the audit layer that tells those skills what to fix, and its action plan is written to be handed to them.
• Use the manual install when Claude Code's plugin system is unavailable, and the plugin install otherwise. The plugin route is the only one with hook enforcement, and it is three commands against a clone-and-script. The manual route exists for other harnesses, which is also why the skills are written to a portable subset of the spec.

What this guide did not verify

Four boundaries, stated plainly. First, the full agent audit was not run here: it needs a Claude Code plan, and the sandbox has none. The audit pipeline, crawl limits, scoring, and output files above are the project's documented behavior from its seo-audit skill, not outputs this guide produced. Second, Chromium rendering was not exercised: setup ran with --skip-browser, so JavaScript-rendered pages and screenshots are untested in this guide. Third, the Google API extensions and paid extensions were not connected: no keys were created, so field data (CrUX, Search Console, Analytics) and DataForSEO results are undescribed beyond the project's docs. Fourth, the network fetch tools were not verified end to end in the sandbox, for the SSRF/DNS reason given in Step 3 — on a normal network they are documented to work, but this guide did not watch them do it. The star counts and the one-day gain are repository data and the GitNova tracker's measurement, retrieved 27 October 2026, not figures this guide reproduced by recounting stars.

The takeaway

Claude SEO's durable idea is not that an agent can audit a website — any agent can be prompted to do that — but that the audit is a product with a fixed pipeline, a score, and a plan. Install it as a plugin, run setup once, check readiness with doctor, and use the launcher for the deterministic tools whenever you want a check without spending model calls. Then, when you do spend them, spend them on the full audit, and judge it by its action plan: are the recommendations ordered by impact, does each one say how you will know it worked, and did the score move when you fixed the top items? If the answer is yes, the plugin has earned its place next to the crawler you already use. If it is no, the deterministic tools alone — the content scorer, the schema generator, the portability checker — are still worth keeping, and they cost nothing.

Sources

• Claude SEO repository and README (AgriciDaniel/claude-seo on GitHub) — install commands, command list, agent table, pricing and cost notes, FAQ, extensions, and uninstall.
• Claude SEO plugin manifest (.claude-plugin/plugin.json, version 2.5.0) and repository data retrieved 27 October 2026 — 22,543 stars, 3,088 forks, 412 commits, MIT licence, created 7 February 2026.
• Claude SEO skill files — seo/SKILL.md (launcher form, command reference), seo-audit/SKILL.md (audit pipeline, crawl configuration, output files, scoring), and AGENTS.md (portability, launcher rule, harness notes).
• GitNova GitHub trending report for 26 October 2026 — claude-seo gained 1,469 stars in 24 hours.