SEOCode Documentation

Install the GitHub App

Go to github.com/apps/seoguard, click Install, and choose which repositories to grant access to. You can select all repos or specific ones.

Open a pull request

SEOCode runs automatically whenever a pull request is opened or updated. No manual trigger needed.

Review the SEO report

A comment appears on your PR listing every issue found, the exact fix to apply, and a link to the relevant spec. The PR status check shows pass or fail depending on whether any critical issues were found.

Contents: Read

Reads repository files at the PR's commit SHA for analysis. Nothing is stored.

Pull requests: Read & Write

Allows SEOCode to post and update the SEO review comment on your pull request. The Write permission is needed only to create and edit that single comment - SEOCode does not merge, close, or modify your PRs in any other way.

Commit statuses: Read & Write

Allows SEOCode to post a pass or fail status check on the PR commit. This is what blocks merging when critical SEO issues are found, and what shows the green checkmark when everything passes.

Remove from specific repos

Go to GitHub → Settings → Applications → Installed GitHub Apps → SEOCode → Configure. Under Repository access, remove the specific repositories you no longer want reviewed.

Uninstall entirely

On the same configuration page, scroll to the bottom and click Uninstall. This removes SEOCode from all repositories and revokes all GitHub permissions immediately.

Cancel your subscription

Uninstalling the app does not cancel billing. If the organization is on Studio, open your dashboard and click Manage billing on it; the organization stays listed there after you uninstall, so you can always cancel. Subscribed through an older checkout link? Cancel in the Polar customer portal instead.

Exclude paths

exclude takes glob patterns - any matching file is skipped entirely. * matches within a path segment, ** matches across segments, and a trailing / excludes a whole directory (e.g. public/legacy/).

Disable or reclassify rules

Under rules, set a rule id to "off" (or false) to disable it, or to "critical", "warning", or "info" to change its severity - which also changes whether it can block a required status check.

Safe by default

Config can only narrow or reclassify what SEOCode reports - it never invents new rules. If the file is missing or malformed, SEOCode runs with its defaults, so a typo can't break your reviews.

Slack

Set slack to an Incoming Webhook URL. In Slack, go to Your apps → Create new app → Incoming Webhooks, enable it, and copy the webhook URL for the channel you want alerts in. Alerts include the PR title, author, the file and rule that triggered, and a direct link to the PR.

Email

Set email to any email address. Alerts are sent from alerts@seocode.io via Resend. Add this address to your allowlist if your inbox filters aggressively. You can use a team alias (e.g. seo-team@yourcompany.com) to reach multiple people at once.

Microsoft Teams

Set teams to a Teams incoming webhook URL. In Teams, go to the channel you want to post in → Connectors → Incoming Webhook → configure and copy the URL. SEOCode posts an Adaptive Card with the PR details and a link to view it on GitHub.

Discord

Set discord to a Discord webhook URL. In your server, go to the channel → Edit Channel → Integrations → Webhooks → New Webhook, and copy the webhook URL. Alerts are posted as embedded messages with the PR link, author, and issues found.

Commands

seocode check scans the repo (or given paths). seocode check --fix applies safe, mechanical fixes to your files (e.g. loading="lazy", rel="noopener noreferrer"). seocode check --staged reviews only git-staged files. seocode check --json prints machine-readable output.

Pre-commit hook

Run seocode init --hook to scaffold a .seocode.json and install a git pre-commit hook that runs seocode check --staged - so broken SEO never even reaches a pull request. It honors the same .seocode.json config as the GitHub App.

Exit codes

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

Where the config goes

Claude Desktop: claude_desktop_config.json. Cursor: Settings → MCP. Claude Code: a .mcp.json in your project. Reload the client after adding the block.

Two tools

audit_file runs the full ruleset against one file and returns issues grouped by severity with the fix for each. suggest_fix returns a deterministic 1-click replacement for a specific issue (by ruleId, optionally line). It never invents a fix.

Config & privacy

The server honors your .seocode.json (rule disables and severity overrides), resolved by walking up from the audited file. It runs entirely on your machine over stdio - free, local, and un-gated. To run a local build instead of npx, point command at node and the built dist/src/mcp/index.js.

geo-robots-ai-agents critical

What it checks: Whether robots.txt contains a Disallow directive targeting AI crawlers - specifically GPTBot (OpenAI), PerplexityBot, ClaudeBot (Anthropic), or Google-Extended (Google AI). A blanket block on any of these agents tells the crawler to skip your content entirely.

Why it matters: AI answer engines can only cite pages their crawlers can reach. Blocking them in robots.txt effectively opts your site out of AI-generated citations and summaries - often unintentionally, as a side-effect of a wildcard Disallow: / rule copied from a staging config.

# flagged - blocks OpenAI's crawler
User-agent: GPTBot
Disallow: /

# fix - allow the agent (or remove the stanza entirely)
User-agent: GPTBot
Allow: /

schema-nested-graph critical

What it checks: JSON-LD entities of type Organization, Person, Product, or Place that are missing an @id property. Without @id, the graph is flat and anonymous - each entity cannot be linked to or referenced from other documents.

Why it matters: AI engines build a knowledge graph by resolving entity identifiers. An entity without @id cannot be merged with the same real-world entity found on other pages or in external knowledge bases, so it contributes nothing to the engine's model of your organization, product, or person.

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#org",  // ← add this
  "name": "Acme Corp",
  "url": "https://example.com"
}

schema-entity-sameas warning

What it checks: Organization or Person schema that has no sameAs array. sameAs should list authoritative external identifiers such as a Wikidata entry, LinkedIn company page, or Crunchbase profile.

Why it matters: AI engines use sameAs to corroborate an entity's identity against their existing knowledge. Without it, your organization may be treated as an unknown or ambiguous entity, which reduces the likelihood of accurate citations and entity-level knowledge panel coverage.

{
  "@type": "Organization",
  "name": "Acme Corp",
  "sameAs": [
    "https://www.wikidata.org/wiki/Q12345",
    "https://www.linkedin.com/company/acme",
    "https://www.crunchbase.com/organization/acme"
  ]
}

geo-ssr-hydration critical

What it checks: Critical metadata - title, description, og:image, or canonical - that is set only inside a useEffect or useState initializer. These hooks are client-only: the metadata does not exist in the server-rendered HTML that crawlers fetch.

Why it matters: AI crawlers behave like traditional search bot crawlers: they read the static HTML response, not a post-hydration DOM. Metadata set via useEffect is simply absent from their perspective - meaning they see no title, no description, and no image for the page.

// flagged - title set after hydration, invisible to crawlers
useEffect(() => { document.title = "Dashboard"; }, []);

// fix - use the framework's server-side metadata API
// Next.js App Router:
export const metadata = { title: "Dashboard" };

// Remix:
export function meta() { return [{ title: "Dashboard" }]; }

schema-faqpage-completeness warning

What it checks: Files that include a FAQPage JSON-LD block but have no corresponding question-and-answer structure in the visible HTML - no heading that matches an FAQ question, and no answer paragraph beneath it.

Why it matters: AI engines cross-reference structured data against the actual page content. A FAQPage schema that has no visible counterpart looks like spam or decoration. Engines that verify structured data against HTML content may ignore the schema entirely, eliminating any FAQ rich-result or citation benefit.

<!-- fix: mirror every FAQ item as visible HTML -->
<section>
  <h3>What is SEOCode?</h3>
  <p>SEOCode is a GitHub App that reviews pull requests for SEO
  and AI discoverability issues automatically.</p>
</section>

geo-bluf-structure info

What it checks: h2 and h3 sections where the direct answer to the implied question appears more than a paragraph into the section - i.e. the section leads with background or narrative before stating the point. BLUF stands for Bottom Line Up Front.

Why it matters: AI engines extract "passages" - self-contained snippets of text - to answer user queries. When the direct answer is buried several sentences in, the relevant passage is harder to isolate and less likely to be surfaced. Leading with the answer improves passage extraction and citation quality without changing the overall content.

• → Lead each section with the direct answer or key claim in the first sentence.
• → Follow with context, evidence, or elaboration in subsequent sentences.

geo-passage-containment warning

What it checks: Heading elements (h2, h3) whose following content is not wrapped in a semantic block element - <article>, <section>, or <aside>. Content that flows directly as siblings of headings inside a generic <div> lacks clear passage boundaries.

Why it matters: AI engines use semantic HTML to determine where a passage begins and ends. Without a containing element, the engine has to infer passage boundaries from heading proximity alone, which is imprecise and makes it harder to extract the right content for a given query.

<!-- flagged: heading and content are bare siblings -->
<div>
  <h2>Our pricing</h2>
  <p>Plans start at $0 per month...</p>
</div>

<!-- fix: wrap in a semantic container -->
<section>
  <h2>Our pricing</h2>
  <p>Plans start at $0 per month...</p>
</section>

geo-unanchored-stats info

What it checks: Numerical statistics - percentages, counts, monetary figures - that appear in body text without an inline citation link anchoring them to a source. The rule looks for patterns like 85%, 2.4 million, or $3B in paragraph text that have no adjacent <a> element.

Why it matters: AI engines apply a credibility signal to claims that are verifiable - a stat linked to its source is treated as asserted evidence rather than unverified copy. Unanchored statistics may be omitted from AI-generated summaries or cited with lower confidence. Linking also benefits traditional SEO through outbound trust signals.

<!-- flagged: numerical claim with no source link -->
<p>Third-party studies show pages with schema rank N% higher within 30 days.</p>

<!-- fix (option A): link the statistic to its source -->
<p><a href="https://example.com/schema-study">According to Schema.org research</a>,
pages with structured data rank measurably higher within 30 days.</p>

<!-- fix (option B): use first-person phrasing -->
<p>In our analysis, pages with schema consistently rank higher within 30 days.</p>