What the agent does
The agent reads how the site is built and what already checks links before adding a tool. In a site like gohugoio/hugoDocs, hugo.toml sets baseURL to https://gohugo.io/, mounts content/en as the content root, requires Hugo 0.144.0 or later, writes Netlify's _redirects and _headers from the redir and headers output formats, and sets params.render_hooks.link.errorLevel to warning. That setting drives layouts/_markup/render-link.html, a render hook that resolves every internal link destination against a content page, a page resource, a section resource or a global asset and, at warning, logs each one it cannot resolve; external destinations pass through untouched. netlify.toml builds production with npm ls && hugo --gc --minify on HUGO_VERSION 0.169.0, package.json brings Tailwind 4 and Alpine.js, go.mod and hugo.work make the site a Go module, and .github/workflows/lint.yml runs markdownlint-cli2, cspell, codespell and a gotmplfmt check on push and pull request, with every action pinned to a commit SHA and a version comment. .gitignore ignores public/, resources/, hugo_stats.json and package-lock.json, so installs use npm i, and AGENTS.md says never to edit the generated content/en/commands/** or data/docs.yaml.
The first change costs nothing new: the agent installs Hugo extended 0.169.0 in its sandbox, runs npm i and hugo --gc --minify, and reads the build log. If the link hook reports no unresolved destination on the current content, it raises errorLevel to error in hugo.toml, so the next renamed page fails the Netlify build and any workflow that builds the site instead of logging a warning nobody reads. If the log does show unresolved links, it fixes them in the Markdown first, in a separate commit, and raises the level after.
The second change checks what the hook cannot: anchors, links written in HTML templates and shortcodes, and the pages that public/ actually contains. A new .github/workflows/links.yml runs on pull requests that touch content/**, layouts/** or hugo.toml, installs Node and the pinned Hugo release read from netlify.toml, builds with the same command Netlify uses, and runs lycheeverse/lychee-action over public/**/*.html in --offline mode with --root-dir public and --base-url set to the site's baseURL, failing the job on a broken internal link or fragment. A lychee.toml excludes localhost, example.com and the placeholder hosts the documentation itself uses in examples, and a .lycheeignore holds the handful of patterns the agent found while running it.
External links go in a separate job in the same file, on a weekly schedule and on workflow_dispatch, without --offline, with lychee's cache and accept list configured so a host that answers 429 to a scanner does not fail the run, and with its Markdown report posted as an issue through peter-evans/create-issue-from-file that is updated rather than duplicated. Both jobs get permissions: contents: read, the weekly one issues: write, actions pinned by SHA with version comments like lint.yml, and a concurrency group. The agent runs the offline check in its sandbox against the built site, runs the external check once to size the ignore list, and keeps both outputs.
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 Hugo site and open a pull request. Read hugo.toml, netlify.toml, package.json, go.mod, hugo.work, .gitignore, AGENTS.md, layouts/_markup/render-link.html, .github/workflows/lint.yml and .markdownlint-cli2.yaml first. Install Hugo extended at the HUGO_VERSION netlify.toml pins, run npm i and hugo --gc --minify, and read the build log for unresolved link destinations from the link render hook; fix any in a separate commit, then raise params.render_hooks.link.errorLevel to error in hugo.toml. Add .github/workflows/links.yml with two jobs: on pull requests touching content, layouts or hugo.toml, build the site with the same Hugo version and command and run lycheeverse/lychee-action over public/**/*.html in --offline mode with --root-dir public and --base-url from baseURL, failing on broken internal links and fragments; and on a weekly schedule and workflow_dispatch, run lychee without --offline over the built site with caching and an accept list for rate-limited hosts, posting the report as a single updated issue with peter-evans/create-issue-from-file. Add lychee.toml and .lycheeignore for localhost, example.com and the placeholder hosts used in the documentation's examples. Pin every action by commit SHA with a version comment as lint.yml does, set least-privilege permissions and a concurrency group. Run the offline check and one external check in the sandbox, and list in the pull request what each found.",
"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 .github/workflows/links.yml, lychee.toml and .lycheeignore, changes one line of hugo.toml, and, when the first build showed unresolved destinations, a separate commit fixing those Markdown links. The description says which Hugo version the workflow installs and where that number is read from, what the offline check found on public/, and what the one external run found, host by host, so the ignore list can be reviewed line by line.
The run's record keeps the hugo --gc --minify log, the offline lychee output and the external lychee output, so a reviewer can see what the render hook warned about and what lychee found without building the site locally.
Before merging, a reviewer decides whether the weekly issue should go to a label or a project, and whether the pull request job should also run on push to master, which lint.yml does and links.yml leaves to them.
Run it on every documentation site with no link check
A team with several Hugo sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own hugo.toml, so a site with no link render hook gets the offline lychee check as its only internal guard, a site that deploys from GitHub Pages gets the check added to the workflow that already builds it, and a site with a different publishDir gets --root-dir pointed at that. Each run opens its own pull request.
Give the API key a webhook_url and Rush POSTs run.completed when each run the key started finishes, with session_url to read the pull request and the link report from, so the broken links each site already has can be triaged in one place.
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 HTML a visitor gets, external hosts on every pull request until a rate limit turns the job red, or a second tool for a check the render hook already does. In a Rush sandbox the agent installs the pinned Hugo, runs the real build, reads its warnings, and runs lychee against the real public/, and every command's output stays in the run, so the pull request shows what was checked and what was found.
The build of a documentation site with a thousand pages, a Tailwind pipeline and an external scan runs on the agent's own machine, not on anyone's laptop, and the same request goes to every site in the org at once. The result is a check that fails for the right reason on the next renamed page.
Frequently asked questions
Doesn't Hugo already check links?
Only through a link render hook, and only when the site has one with errorLevel set. The hook in layouts/_markup/render-link.html resolves Markdown link destinations at build time; it does not check fragments, links in templates or shortcodes, or external hosts. The pull request raises the hook to error and adds lychee for the rest.
Why run the external check weekly instead of on every pull request?
External hosts answer slowly, rate-limit scanners and go down on their own schedule, none of which a pull request author can fix. The offline check on public/ is deterministic and fast and fails the pull request; the external check runs weekly and reports in an issue that is updated in place.
Which Hugo version does the workflow use?
The one netlify.toml pins in HUGO_VERSION, read by a step in the workflow rather than copied, so bumping Netlify bumps CI. The extended build is used because the site's Tailwind pipeline needs it.
Will it fail on links in generated pages like content/en/commands?
Those pages are built into public/ like any other and are checked. If one carries a broken link, the fix belongs in the generator that writes them, which AGENTS.md says not to edit by hand, so the pull request lists such a case for the maintainers rather than editing the file.