seo-codebase-auditor
Honest, codebase-only SEO audits for Next.js, Shopify, WordPress, and modern web projects — generated by Claude Code from the evidence in your repository.
A Claude Code community plugin that audits your website/app source code for SEO and writes a structured, reproducible report. It reads your real files — metadata, schema, sitemap, robots, canonicals, images, components, templates — and grades what it actually finds.
It will never invent traffic, rankings, backlinks, domain authority, AI citations, GA4, or Search Console data. Anything that can't be proven from the codebase is reported as “Not available from codebase.”
What it does
- Detects your project type from manifest and signature files.
- Inspects only the files that actually exist in the repo.
- Audits 13 codebase-verifiable SEO areas and scores each with a transparent, weighted model.
- Writes three report files into the project so the audit is shareable and reproducible.
- Produces a prioritized, developer-ready action plan.
- Exports that action plan to a shared Google Sheet tracker (priorities, assignees, status) on demand.
What it audits
- Technical SEO — indexability, crawlability, rendering mode, error/page structure
- Metadata — titles, descriptions, Open Graph, Twitter cards, robots meta, placeholder/duplicate risks
- Schema — JSON-LD: Organization, WebSite, Article/BlogPosting, Product, BreadcrumbList, FAQPage
- Sitemap — static,
app/sitemap.ts, next-sitemap, or plugin-generated
- Robots.txt — accidental blocking, sitemap declaration, AI crawler rules
- Canonicals — implementation, missing/wrong risks, localhost/staging URL leaks
- Internal links — nav/footer/content links, empty hrefs, orphans, external
rel hygiene
- Image optimization —
next/image vs raw <img>, alt text, LCP/CLS, lazy loading, remote config
- Accessibility basics — headings, semantic HTML, labels, ARIA
- Performance setup — static/ISR/caching, font/script loading, third-party scripts, bundle risk
- Framework SEO — Next.js, Shopify, and WordPress specific implementation details
- Content structure — hierarchy, blog/article structure, freshness signals, topic clusters
- AI visibility readiness — entity clarity, author/company signals, citation-friendly structure,
llms.txt
What it does NOT audit
This is a static, codebase-only tool. It has no crawler, browser, or API access. It does not measure or estimate:
- Organic traffic, sessions, pageviews
- Keyword rankings, impressions, clicks, CTR
- Backlinks or referring domains
- Domain authority / domain rating
- AI citation counts or any “AI visibility score”
- Google Search Console data
- GA4 / analytics data
- Real SERP performance or competitor comparisons
Those require live data sources. The plugin marks every such item as “Not available from codebase.”
Supported frameworks
| Detected | Notes |
|---|
| Next.js | App Router & Pages Router, metadata API, sitemap.ts/robots.ts, next/image, next/font |
| Shopify | Liquid themes (theme.liquid, templates, sections, snippets) and Hydrogen |
| WordPress | Classic & block themes (functions.php, wp_head, theme.json, template parts) |
| Astro / Nuxt / Remix / Gatsby | Framework-idiomatic head/meta, sitemap, and image checks |
| Vite / React (SPA) | Flags client-only rendering and prerender configuration |
| Static HTML | Raw <head>, links, images, and structured data |
| Unknown | Universal checks only; scores honestly as N/A where evidence is thin |
Installation
Clone or download this plugin, then point Claude Code at it:
claude --plugin-dir ./seo-codebase-auditor
You can also place it in your Claude Code plugins directory or install it from a marketplace that lists it.
Local usage
- Open Claude Code inside the repository you want to audit.
- Load the plugin (see installation).
- Run the command:
/seo-codebase-auditor:audit
Example prompt
For a fully explicit, honesty-first run, paste:
/seo-codebase-auditor:audit
Audit this project codebase only. Do not invent traffic, keywords, backlinks, domain authority, or AI visibility rankings. Generate reports/codebase-seo-audit.md, reports/codebase-seo-action-plan.md, and reports/codebase-seo-evidence.json.
Output files
The audit writes three files into the audited project:
| File | Purpose |
|---|
reports/codebase-seo-audit.md | Full 18-section report with scores, grades, evidence, and per-category findings |
reports/codebase-seo-action-plan.md | Prioritized fixes (High/Medium/Low) ranked by Impact + Confidence − Effort |
reports/codebase-seo-evidence.json | Machine-readable evidence: files reviewed, files missing, per-category scores, and an explicit notAvailableFromCodebase list |
