SEOCode

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 your editor (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.

Works in any MCP client - Cursor, Claude Desktop, Claude Code, and OpenAI Codex.

Cursor / Claude Desktop / Claude Code - use the JSON block (Cursor's MCP settings, claude_desktop_config.json, or a project .mcp.json):

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

OpenAI Codex - add to ~/.codex/config.toml:

[mcp_servers.seocode]
command = "npx"
args = ["-y", "-p", "@qobi/seocode", "seocode-mcp"]

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

ChatGPT's own connectors require a hosted remote MCP server, so this local server plugs into editors and agents, not the ChatGPT app.

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.

License

© SEOCode. Free to install and run, including at work and in CI. Redistributing it, or extracting the ruleset, is not permitted — see LICENSE. Versions before 0.4.5 were published under MIT.