What the agent does
An mdBook's CI often checks links already, so the agent reads what the existing check covers before adding another. In a book laid out like rust-lang/rust-by-example, book.toml names the title, sets edit-url-template and git-repository-url under [output.html], enables the editable playground and folding, adds theme/css/language-picker.css, and declares an optional gettext preprocessor for the translations under po/. .github/workflows/rbe.yml is the one workflow: it installs a pinned mdbook from the release tarball and mdbook-i18n-helpers through cargo install, runs mdbook test and mdbook build, then downloads linkcheck.sh from the linkchecker tool in rust-lang/rust and runs it against the built book directory, once for the source and once per language in LANGUAGES. That tool checks the links inside the built HTML against the local tree and the installed rust-docs; it never fetches an http or https address. So the book's outbound links, the ones to crates, blog posts and external references scattered through the Markdown under src/, are never checked, and they are the ones that rot.
The agent writes .github/workflows/links.yml around lycheeverse/lychee-action, pinned to its current major. It runs on a weekly schedule, on workflow_dispatch, and on pull_request for changes under src/. The step restores a .lycheecache with actions/cache/restore, runs lychee with --cache --max-cache-age 1d so a link that answered yesterday is not fetched again, --root-dir set to the checkout so absolute paths resolve, and the inputs src/**/*.md and README.md while excluding po/, whose .po files repeat every link once per language. On the schedule the step has fail: false and is followed by peter-evans/create-issue-from-file with issues: write, so a broken link becomes one issue with lychee's Markdown report rather than a red badge nobody reads; on a pull request fail is left on so a new dead link blocks the merge. The cache is saved with actions/cache/save under if: always(), the pattern the action's README recommends so a failing run still updates it.
Two files shape what lychee ignores. .lycheeignore lists patterns that cannot or should not be fetched from a runner: play.rust-lang.org links, which the editable playground generates and which carry code in the query string, localhost and 127.0.0.1 examples, and any address the book uses as a placeholder. lychee.toml sets accept to include the status codes GitHub returns for rate limiting, a max-retries and timeout, a user-agent, and exclude-loopback, and the workflow passes the repository's GITHUB_TOKEN as token so links to github.com are not throttled. .lycheecache is added to .gitignore. The agent does not touch rbe.yml; the local-link check it runs is a different job and stays.
To see what the first run will report, the agent installs lychee in its sandbox from the project's release and runs lychee --no-progress --root-dir . 'src/**/*.md' README.md with the same ignore file and config, then runs it a second time with --cache to show the second pass is quick. The pull request pastes the summary line and lists every address lychee reports as broken, timed out or excluded, grouped by file, so the first scheduled run on GitHub holds no surprises. The agent fixes none of those links itself; which address to update and which to drop is an editorial call for the book's maintainers.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add external link checking to this mdBook. Read book.toml, .github/workflows/rbe.yml, README.md, CONTRIBUTING.md, .gitignore and the layout of src, theme and po first, and say in the pull request what the existing linkcheck.sh step does and does not cover. Write .github/workflows/links.yml using lycheeverse/lychee-action on a weekly schedule, workflow_dispatch and pull requests that touch src, with a restored and always-saved .lycheecache, --cache --max-cache-age 1d, --root-dir set to the checkout, src/**/*.md and README.md as inputs, po excluded, the GITHUB_TOKEN passed as token, fail false plus peter-evans/create-issue-from-file on the schedule and fail true on pull requests. Add a .lycheeignore for playground, localhost and placeholder addresses and a lychee.toml with accept codes, retries, timeout and user agent. Add .lycheecache to .gitignore. Install lychee in the sandbox, run it twice to show the cache, and open a pull request listing every link it reports, grouped by file, without fixing any.",
"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
The pull request adds .github/workflows/links.yml, .lycheeignore and lychee.toml, and adds one line to .gitignore. Its description explains the gap between the existing linkcheck.sh step and outbound links, pastes lychee's summary from the sandbox run and the shorter second run with the cache, and lists each reported address under the Markdown file that contains it.
The pull request itself triggers the new workflow when it touches src/, which it does not, so the first run is the one a maintainer starts from the Actions tab with workflow_dispatch or the first weekly schedule; its Markdown report lands as an issue. The run's record on Rush keeps both sandbox invocations so the list in the pull request can be checked against lychee's own output.
Before merging, a reviewer picks the schedule day, decides whether pull requests should block on a dead outbound link or only report, and goes through the listed addresses to fix or ignore each. The book's content and the existing CI workflow are unchanged.
Run it on every mdBook repository whose outbound links go unchecked
An organisation with several books starts one run per repository from its own server: a POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own book.toml and workflows, so a book that already runs lychee gets a report of what its configuration misses, and a book with no CI at all gets the local-link check proposed in the same pull request.
The scheduled workflow does the weekly checking on GitHub. For the follow-up, an automation in the Project with a github trigger on issues.labeled, filtered to a fix-links label, and the prompt "if this issue is a Link Checker Report, open a pull request that updates each moved link to its new address where the redirect target is clear and lists the rest for a maintainer" turns the report into a reviewable change once a maintainer adds that label to the report. The trigger adds the issue after the prompt and fires only for work by owners, members and collaborators; the issue the workflow opens with its own token comes from a bot sender, which never fires a trigger, so the maintainer's label is what starts the run.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Link checking is one of those jobs where the configuration is the work: without a cache the weekly run hammers the same hosts and trips rate limits, without an ignore file every playground link fails, and without fail: false on the schedule the badge turns red the first week and stays red. The agent reads what the book already checks, runs lychee for real in its sandbox against the actual Markdown, and ships the workflow with the first report already in hand.
Every command stays with the run, including both lychee passes, and the pull request quotes them. Several books get the same workflow at once, each checked on its own machine with its own list of addresses.
Frequently asked questions
Does this replace the existing linkcheck.sh step?
No. That step checks the links inside the built HTML against the local tree and the rust-docs component, which catches a broken anchor or a renamed chapter. Lychee fetches outbound http and https addresses, which that tool skips. The two jobs are complementary and the pull request keeps both.
Why run the schedule with fail false and open an issue?
Because an outbound link breaks on someone else's server at any time, and a red scheduled workflow is easy to ignore. An issue with lychee's Markdown report is something a maintainer triages. On pull requests the check fails, since a new dead link is the author's to fix.
What goes in .lycheeignore?
Addresses that cannot or should not be fetched from a runner: the playground links the editable code blocks generate, localhost examples, and placeholder domains used in prose. The agent lists each pattern with the reason in a comment, and the sandbox run shows what each one excludes.
Will lychee check the translations?
Not by default. The po/ directory repeats every link once per language in .po files, which would multiply the work and the noise without finding anything new. A team that wants the built translations checked can add the book/<lang> output as a second input once the book is built in the same job.