Framework-aware technical SEO review for your codebase. A zero-config CLI that catches deploy-blocking SEO regressions - accidental noindex, dynamic metadata that never renders, broken JSON-LD, missing titles - before you push, right in your terminal.

It understands your framework. Titles and descriptions set through the Next.js Metadata API / generateMetadata, Remix meta(), or Astro layouts are read the way the framework actually renders them - so you don't get false "missing title" noise on correct code.

npx @qobi/seocode check

Install

# one-shot, no install
npx @qobi/seocode check

# or install globally - the command is just `seocode`
npm i -g @qobi/seocode
seocode check

Requires Node.js ≥ 20.

Commands

seocode check                 # scan the repo (or given paths) for SEO issues
seocode check src/ app/       # scan specific paths
seocode check --fix           # scan, then apply safe, mechanical fixes to your files
seocode check --staged        # review only git-staged files (pre-commit mode)
seocode check --json          # machine-readable output (for editors / CI)
seocode init                  # create a .seocode.json + set up a pre-commit hook
seocode init --hook           # also install .git/hooks/pre-commit for you

Exit code is 1 when deploy-blocking (critical) issues are found, 0 otherwise - so it drops straight into a pre-commit hook or a CI step.

What it checks

Critical, deploy-blocking issues are surfaced first; lower-severity suggestions stay out of the way.

Critical - accidental noindex, missing <title>, broken/invalid JSON-LD, unrendered dynamic metadata, missing <h1>, duplicate <h1>, images missing alt
Warnings - title/description length, missing Open Graph / Twitter tags, broken heading hierarchy, missing canonical, vague link text
Info - lazy-loading hints, AVIF format, LCP preload, structured-data recommendations, and more

…across HTML, JS, JSX, TSX, Vue, Svelte, and Astro files. Framework shells, utility files, and component libraries are scoped automatically.

`--fix`

--fix applies only the transforms SEOCode can make with certainty - never a guess. Today that covers:

adding loading="lazy" to images that lack it
adding rel="noopener noreferrer" to external links that have no rel

Everything else is reported with the exact tag to add and the line to change.

Framework awareness

SEOCode reads framework metadata instead of just literal tags, so it won't false-flag idiomatic code:

Next.js - metadata / generateMetadata, App Router layouts & pages, next/og image routes, JSON-LD via dangerouslySetInnerHTML
Remix - meta() exports
Astro - layouts with dynamic <title>{title}</title>, pages that delegate their <head> to a layout
Plain HTML / Vue / Svelte - the <head> is checked directly

The head is composed by the framework across layouts, pages, and merged metadata - so on framework files, SEOCode reports only what it can prove, and stays silent where it can't. Real signal (like an accidental noindex) still comes through.

Configuration

Drop a .seocode.json in your repo root (all fields optional):

{
  "exclude": ["emails/**", "public/legacy/**", "**/*.stories.tsx"],
  "rules": {
    "title-too-short": "off",
    "missing-canonical": "info"
  }
}

exclude - glob patterns to skip (* within a segment, ** across segments, trailing / for a whole directory)
rules - set a rule to "off" (or false) to disable it, or to "critical" / "warning" / "info" to change its severity

A missing or malformed config falls back to defaults - a typo can't break your reviews.

Pre-commit hook

seocode init --hook          # installs .git/hooks/pre-commit → seocode check --staged

…or with husky:

echo "npx @qobi/seocode check --staged" > .husky/pre-commit

Use it in Cursor & Claude (MCP)

SEOCode ships an MCP server (seocode-mcp) so you can run the same engine inside your AI editor. Ask your assistant "audit this file for SEO issues" and it runs the full ruleset locally - nothing leaves your machine. Two tools: audit_file and suggest_fix (deterministic 1-click fixes). It honors your .seocode.json.

Claude Desktop / Claude Code - add to claude_desktop_config.json (or a project .mcp.json):

{
  "mcpServers": {
    "seocode": {
      "command": "npx",
      "args": ["-y", "-p", "@qobi/seocode", "seocode-mcp"]
    }
  }
}

Cursor - Settings → MCP → Add new, or add to .cursor/mcp.json:

{
  "mcpServers": {
    "seocode": {
      "command": "npx",
      "args": ["-y", "-p", "@qobi/seocode", "seocode-mcp"]
    }
  }
}

Reload your editor, then ask: "audit app/page.tsx for SEO issues."

SEOCode as a GitHub App

Prefer automated reviews on every pull request instead of (or alongside) the CLI? The hosted SEOCode GitHub App posts a critical-first review comment on every PR, offers one-click fixes, sets a merge status check, and judges each PR on what it changed (legacy debt never blocks your merge). See seocode.io.