What the agent does
The agent reads the site's config before adding a tool, because Starlight has a plugin system and a link checker that fits it is better than one bolted onto the HTML. In a site made from the basics example in withastro/starlight, package.json has @astrojs/starlight 0.42, astro 7 and sharp, with dev, build and preview scripts and nothing else. astro.config.mjs registers starlight() with a title, a GitHub social link and a sidebar whose Guides group names guides/example by slug and whose Reference group is autogenerated from src/content/docs/reference/. src/content.config.ts loads the docs collection with docsLoader and docsSchema. There are three pages, no site in the config, no .github/ directory and no link check of any kind; index.mdx links to /guides/example/ from its hero and both example pages link out to diataxis.fr.
For internal links the agent installs starlight-links-validator, the Starlight plugin that runs during astro build, walks every Markdown and MDX page, and reports each link to a page or heading that does not exist. It adds starlightLinksValidator() to the plugins array of starlight() in astro.config.mjs with the defaults left visible: errorOnRelativeLinks, errorOnInvalidHashes and errorOnLocalLinks on, errorOnFallbackPages on, errorOnInconsistentLocale off, sameSitePolicy at ignore, and failOnError on so the build exits non-zero. It sets site in defineConfig to the production URL, because turning sameSitePolicy to validate later needs it and Astro's sitemap does too. The plugin's GitHub Actions reporter is on by default, so a failing build annotates the offending line in the pull request.
External links are a different problem: a build that fails because diataxis.fr is slow would block every pull request, so those get a scheduled job. The agent writes .github/workflows/links.yml with two jobs. internal runs on pull_request and push: actions/setup-node with the npm cache, npm ci, npm run build. external runs on a weekly schedule and workflow_dispatch: the same build, then lycheeverse/lychee-action over dist/**/*.html with --accept 200,429, and it opens an issue on failure rather than failing a pull request. Both jobs set permissions: contents: read, and the external one adds issues: write.
Before opening the pull request the agent proves the check bites. In its sandbox it runs npm ci and npm run build and reads the clean output; then it edits src/content/docs/guides/example.md to link to /guides/missing/ and to #no-such-heading on the reference page, runs the build again, and keeps the two reported lines and the Found 2 invalid links in 1 file summary; then it restores the file and builds once more. It runs actionlint on the workflow. The pull request shows all three builds.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add link checking to this Starlight docs site. Read package.json, astro.config.mjs, src/content.config.ts, every page under src/content/docs and anything under .github first. Install starlight-links-validator and add it to the starlight plugins in astro.config.mjs with its options written out, set the site URL in the Astro config, and add a GitHub Actions workflow with a job that builds on every pull request so an invalid internal link or hash fails the check, and a separate weekly job that runs lychee over the built HTML for external links and opens an issue instead of failing a pull request. Build in the sandbox, then break one internal link and one hash on purpose, build again to capture the failure output, restore the pages and build a third time. Run actionlint on the workflow and open a pull request that shows the three builds.",
"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 a pull request that adds starlight-links-validator to devDependencies, changes astro.config.mjs by the site line and the plugins block, and adds .github/workflows/links.yml. The description shows the clean build, the deliberately broken build with its two annotated lines, and the restored build, plus the actionlint output.
The run's record keeps npm ci, every astro build and the edit and restore of the example guide, so a reviewer can see the plugin fail a real build and not take it on trust.
Before merging, a reviewer sets the site value if the agent's guess from the repository name is wrong, decides whether errorOnRelativeLinks should stay strict for a site whose authors write ./other-page links, and whether the weekly job should run more often. The agent leaves the three content pages exactly as it found them.
Run it on every documentation site with no link check
A team with several Starlight sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retry returns the run already started. Each run reads its own astro.config.mjs, so a site that already has starlightLinksValidator in plugins gets only the workflow, a site with locales gets errorOnInconsistentLocale turned on and the fallback-page rule explained, and a site on pnpm gets pnpm install --frozen-lockfile in the job. Each run opens its own pull request.
After that, an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request renames or moves a page under src/content/docs, list every page that links to the old slug and say whether a redirect is needed" reads each docs change. The trigger adds the pull request after the prompt; it fires for owners, members and collaborators, never for a fork.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A link check added without reading the site checks the wrong thing: source Markdown instead of the built pages, so a wrong slug in the sidebar passes; every external host on every pull request, so a rate limit turns the job red for an hour; or a tool that does not know Starlight's locale fallback and flags every untranslated page. In a Rush sandbox the agent installs the real plugin, runs the real build, breaks a link to watch the build fail and restores it, so the pull request carries behaviour and not intent.
Every command stays with the run, from npm ci to the three builds, and the pull request cites them. Doing the same across a dozen documentation sites costs no more attention than one, because each run has its own machine, its own record and its own pull request.
Frequently asked questions
Does Starlight not check links already?
No. A link to a page that does not exist renders as a link and 404s for the visitor. starlight-links-validator is the plugin the Starlight project itself uses for its own docs; it runs inside astro build, resolves every internal link and hash against the pages the build knows, and with failOnError fails the build.
Why keep external links out of the pull request check?
Because a slow or rate-limiting host outside your control should not block a docs change. Internal links are deterministic and run on every pull request through the build; external ones run weekly through lychee over dist/, and a failure opens an issue with the list of dead links rather than a red check on someone's typo fix.
Will it flag links in the hero on the index page?
The plugin validates links in Markdown and MDX content. The hero actions in index.mdx frontmatter are a different path, so the agent checks them in the sandbox by breaking one and reading the output, and says in the pull request whether the plugin caught it or whether the weekly lychee pass over the built HTML is what covers it.
Does it slow the build down?
The validation runs after the pages are built and walks the links the build already produced; on a site of three pages the difference is not measurable, and the agent reports the build time it saw on your site rather than a number from elsewhere. astro dev is untouched, since the plugin only runs on astro build.