What the agent does
The agent reads how the site is built and where its links come from before it adds a checker, because an Eleventy site rewrites links at build time and a check on the sources would miss what readers click. In a site made from 11ty/eleventy-base-blog, npm run build is npx @11ty/eleventy with content as input and _site as output, on Node 22 from .nvmrc, and eleventy.config.js loads InputPathToUrlTransformPlugin, which turns href="blog.njk" in content/index.njk and href="index.njk" in content/404.md into real URLs in the HTML, and HtmlBasePlugin, which prefixes every absolute link when build-ghpages passes --pathprefix=/eleventy-base-blog/. The feed lives at /feed/feed.xml, tag pages at /tags/<tag>/, and images pass through from public/. External links are few and telling: content/404.md lists hosting guides on 11ty.dev, GitHub, GitLab, Netlify, Cloudflare and Vercel, _includes/layouts/base.njk links https://www.11ty.dev/ in the footer, and _data/metadata.js and the feed's base in the config point at https://example.com/, a placeholder that a checker must not report.
The only workflow is .github/workflows/gh-pages.yml.sample, which deploys on pushes to main with every action pinned by commit SHA and a version comment, and .github/dependabot.yml updates npm monthly while its github-actions block is commented out. The agent adds .github/workflows/links.yml with two jobs. On pull requests and pushes it builds with the plain npm run build, so links are root-relative without a path prefix, and runs lycheeverse/lychee-action, pinned the same way as the sample, with --offline and --root-dir _site over _site/**/*.html and the feed, so a renamed post, a mistyped tag URL or a missing image fails the check in seconds without touching the network. On a weekly schedule a second job runs lychee without --offline on the same build, retries the hosts that rate-limit and uploads lychee/out.md as an artifact, since external links rot on their own schedule and should not block a pull request about a typo.
A .lycheeignore excludes example.com, the mailto: placeholder in metadata.js and the hosting providers' anchors that return 403 to robots, each with a comment saying why, and the agent uncomments the github-actions block in dependabot.yml so the new action gets the same monthly updates as npm. It also notes that fifthpost.md carries draft: true and the drafts preprocessor drops it from a build, so links in drafts are not checked until they publish.
To prove the setup, the agent installs with npm ci, builds, and runs lychee in its sandbox in both modes, first offline, then online once, and reads the results. Anything the offline run reports in the site's own pages it fixes in the content or templates in the same branch; anything the online run reports it lists in the pull request with the status code, fixing only the ones with an obvious replacement, such as a moved documentation page.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add broken link checking to this Eleventy site's CI. Read eleventy.config.js, package.json, .nvmrc, the templates under _includes, the content directory, .github/workflows and .github/dependabot.yml first. Build the site with npm run build and run lychee over _site in your sandbox. Add a workflow with an offline check of the built site, using _site as the root directory, on every pull request and push, and a weekly job that checks external links and uploads its report. Add a .lycheeignore for placeholder domains with a comment per entry, pin the action by commit like the existing sample workflow, enable Dependabot for GitHub Actions, fix any broken internal links you find, list external failures with their status codes, and 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 a pull request on its own branch adding .github/workflows/links.yml and .lycheeignore, uncommenting the github-actions block in .github/dependabot.yml, and changing content or templates only where the offline check found a broken internal link. eleventy.config.js, the layouts and the deploy sample are otherwise untouched.
The description quotes lychee's summary lines from both sandbox runs, the count of links checked and the count excluded, lists every external failure with its status code and whether it was fixed or left, and explains the two-job split in a sentence: internal links block, external links report. It also says where the weekly report lands and how to make it open an issue instead if the team prefers.
Before merging, a reviewer reads the ignore file to confirm each entry is a placeholder and not a real broken link, opens the pull request's link check to see it pass, and decides whether the weekly job should fail or only report.
Run it on every new content site in your organization
A handler on your server receives GitHub's organization repository event, checks its signature, and when the new repository has an eleventy.config.js, sends this body to POST /o/{org}/sessions with the repository in resources; GitHub signs its webhooks and cannot add the Authorization header a Rush webhook trigger needs, so it does not call the trigger directly. The handler sends a request_id that is a UUID v5 of the delivery id, so GitHub's redeliveries return the run already started.
With a webhook_url on the key, Rush POSTs run.completed when the turn ends, and the handler reads the pull request from the session. Every new site then starts with its internal links checked on each pull request and its external links reported weekly, with the transcript showing what the first check found.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A link checker on an Eleventy site is a few lines of YAML and several ways to get them wrong: checking sources instead of output, checking a path-prefixed build against the root, letting a placeholder domain fail every run, or letting one dead external page block every pull request. The agent reads the build pipeline and the real links first and splits the job the way the failures split.
On Rush the build and both lychee runs happen in the agent's own sandbox, and the transcript keeps their output, so the pull request's list of what was broken and what was fixed is backed by the runs that found it. Many sites can be checked the same day, each in its own sandbox with its own pull request.
Frequently asked questions
Why check the built site rather than the Markdown?
Because the HTML is what readers get. The input-path transform rewrites blog.njk into a URL at build time, tag pages and the feed exist only in _site, and the base plugin can add a path prefix. Checking _site with --root-dir _site resolves every root-relative link the way the server would.
Will a dead external link fail my pull request?
No. The pull request job runs offline and only checks links inside the site, which are the ones a change can break. External links are checked by the weekly job, which uploads a report; the pull request shows how to make that job open an issue or fail if the team wants it louder.
What goes in .lycheeignore?
Placeholders and known false positives only, each with a comment: example.com from metadata.js and the feed configuration, the mailto: placeholder, and hosts that answer robots with 403. A real broken link is fixed or listed in the pull request, never ignored.
Does the deploy workflow change?
No. The GitHub Pages sample keeps building with the path prefix and deploying on pushes to main. The link workflow builds separately without the prefix so internal links resolve against the site root, and only the github-actions entry in dependabot.yml is turned on so both workflows get action updates.