What the agent does
The agent clones the repository into its own sandbox, installs with the lockfile and builds, because an SEO audit of a Gatsby site is an audit of the HTML in public/, not of the JSX. In a blog like gatsbyjs/gatsby-starter-blog, package.json asks for gatsby ^5.14.6 with React 18, installs with npm from package-lock.json, and its test script only prints a reminder to write tests and exits 1, so the build is the only automated check. gatsby-config.js sets siteMetadata with the title, an author object, a description, a siteUrl that ends in a slash, and social.twitter, and loads gatsby-plugin-image, two gatsby-source-filesystem sources for content/blog and src/images, gatsby-transformer-remark with gatsby-remark-images at maxWidth 630, gatsby-remark-responsive-iframe and gatsby-remark-prismjs, the sharp plugins, gatsby-plugin-feed writing /rss.xml, and gatsby-plugin-manifest with minimal-ui and src/images/gatsby-icon.png. There is no sitemap plugin and no canonical plugin, gatsby-ssr.js sets lang to en on <html>, and static/robots.txt allows everything and names no sitemap.
The metadata comes from one component. src/components/seo.js is a Head component that renders <title> as the page title joined to the site title with a pipe, a description meta that falls back to the site description, og:title, og:description, an og:type that is always website, a twitter:card of summary, twitter:creator from social.twitter, and the Twitter title and description, and nothing else: no og:url, no og:image, no canonical <link>. src/templates/blog-post.js passes post.frontmatter.description || post.excerpt to it, wraps the article in schema.org Article microdata with itemProp on the headline and body but no datePublished or author properties and no JSON-LD, and renders previous and next links with rel="prev" and rel="next". src/pages/index.js titles itself All posts and prints each post's description or excerpt, src/pages/404.js is titled 404: Not Found, and src/pages/using-typescript.tsx is a page most blogs forget they ship. gatsby-node.js creates a page per allMarkdownRemark node with the slug from createFilePath, which carries a trailing slash, and types the frontmatter as title, description and date in createSchemaCustomization.
The crawl is of the build output served locally. The agent runs npm ci and npm run build, starts gatsby serve, and fetches every HTML file under public/: the index, each post, the TypeScript page and the 404. For each it checks the title and its length, that a description is present and whether it is an excerpt cut mid-sentence, html lang, one h1 per page (the Layout renders the site title as an h1 only on the root path, and a post renders its headline as h1), image alt text that gatsby-remark-images copies from the Markdown, the og:type on posts, the absent og:url, og:image and canonical, and the microdata against what a rich result needs. It reads public/rss.xml and checks each item's link and guid, which gatsby-plugin-feed builds as site.siteMetadata.siteUrl + node.fields.slug; with a siteUrl ending in a slash and a slug starting with one, the audit reports exactly what that concatenation produced. It reads public/robots.txt and public/manifest.webmanifest, confirms there is no sitemap-index.xml, and checks that the 404 page is not linked from anywhere as a real page.
Every finding points at a line and a fix. The og:type goes on a prop that blog-post.js sets to article; a canonical and og:url come from siteUrl and the page path, and an og:image from a frontmatter field or a default under src/images; the microdata gains datePublished and author or is replaced by JSON-LD built from the same query; the feed URL fix is a siteUrl without the trailing slash or a new URL(slug, siteUrl) in the serializer; the sitemap is a plugin install with a Sitemap: line in static/robots.txt. The report groups findings by page type, notes which are plugin installs and which are edits to seo.js, and says which pages are affected, with the run leaving the repository unchanged.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Audit this Gatsby blog for technical SEO and write seo-audit.md. Read package.json, gatsby-config.js, gatsby-node.js, gatsby-ssr.js, src/components/seo.js, src/components/layout.js, src/templates/blog-post.js, the files under src/pages and static/robots.txt first. Run npm ci and npm run build, start gatsby serve, and fetch every HTML page under public plus rss.xml, robots.txt and the web manifest, keeping each response. For every page check the title and its length, the meta description and whether it is a truncated excerpt, html lang, one h1, image alt text, canonical, og:url, og:image, og:type, Twitter tags and structured data, and for the feed check that each item link and guid is a well-formed absolute URL as built from siteUrl and the slug. Check robots.txt for a Sitemap line and whether a sitemap was generated. For each finding name the file and line that produces it, the pages affected, and the change you would make, and mark whether the fix is an edit or a plugin install. List what you checked and found correct as well. Do not change any file and do not open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is seo-audit.md as an artifact on the session, with a download link good for an hour that reading the session again renews. It opens with how the site was built and crawled: the Gatsby and Node versions, the install and build commands, and the list of pages fetched. Then come the findings grouped by what produces them: the gaps in src/components/seo.js with the line each tag would be added at, the og:type and structured data on src/templates/blog-post.js, the feed URLs as gatsby-config.js builds them with the exact strings read from public/rss.xml, and the missing sitemap and robots.txt line. Each names the pages affected and whether the fix is an edit or a plugin.
The session read at GET /o/{org}/sessions/{id} lists the artifact with its name, mime_type and url, and the transcript at GET /o/{org}/sessions/{id}/messages keeps the build output and every fetched page with its headers, so a finding can be checked against the HTML it came from. The repository is unchanged.
A reader picks the findings worth doing, since a three-post blog does not need every rich result, and a follow-up on the same session can apply the seo.js edits and the plugin install as one pull request with a rebuilt public/ to diff.
Run it on every merge to main
Add an automation to the Project with this prompt and a github trigger on pull_request.closed.merged with branch_patterns set to main, so every merge rebuilds the site in a sandbox and audits the output before the deploy settles. The trigger adds the pull request event after the prompt and fills in nothing; only merges by someone who can write to the repository fire it, and the automation's max_runs_per_hour, between 1 and 30, caps a busy afternoon of merges.
A schedule trigger with cron set to one morning a week and your timezone does the same on a cadence. From a deploy hook instead, send POST /o/{org}/sessions with this body and a request_id that is a UUID v5 of the commit SHA, give the key a webhook_url, and Rush POSTs run.completed with data.session_url to read for the artifact.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
The tags a Gatsby page ships are decided at build time by a Head component, a template and a plugin's serializer, and the only honest way to audit them is to build and read public/. That means npm ci, a sharp build and a local server, which is slow on a laptop and never happens for a blog nobody is actively developing. The agent builds it in its own sandbox, reads every page it produced, and maps each gap back to the line that caused it.
The report comes with its evidence: the HTML and the feed as fetched, the build log, and the file and line behind each finding, all on the session. Nothing is changed in the repository, several sites can be audited at once in separate sandboxes, and the parked session can apply the chosen fixes as a pull request without a second build.
Frequently asked questions
Will it edit seo.js or open a pull request?
No. This run reads, builds and reports. Each finding names the file and line where the fix goes, and a follow-up on the same session can make the edits and the plugin install as one pull request, with the rebuilt output to compare.
Does it need my production domain?
It reads siteUrl from siteMetadata in gatsby-config.js, which is what the feed and any canonical would use, and reports if it is still the starter's placeholder. The crawl itself runs against gatsby serve in the sandbox, so no request reaches your domain.
Is the feed URL finding real or a guess?
It is read from public/rss.xml after the build. The serializer in gatsby-config.js joins siteUrl and fields.slug with a plus sign, and the report quotes the resulting link and guid strings as produced, so you see the exact URL a reader would get, and the fix is one line in the config.
Does it check structured data?
Yes. It reads the schema.org Article microdata in blog-post.js and the properties it sets, compares them with what a rich result needs, and reports the missing datePublished and author along with the option of JSON-LD built from the same page query.
Is this a Lighthouse run?
No. This audit is of the HTML, feed, manifest and robots rules the build emits, mapped to source lines. Performance scores and Core Web Vitals are a different measurement; ask for a Lighthouse run against the served build as a follow-up on the session if you want both.
More Gatsby jobs
The same job on other stacks
- Run an SEO Audit on a Next.js Site (Next.js)
- Run an SEO Audit on a Nuxt App (Nuxt)
- Run an SEO Audit on a Starlight Site (Starlight)