What the agent does
The agent starts with what VitePress already checks and what it does not. In a site laid out like vuejs/blog, .vitepress/config.ts sets cleanUrls: true and a buildEnd hook, genFeed, that loads posts/*.md with createContentLoader and writes feed.rss into the output directory; package.json pins vitepress 1.3.4 under packageManager: pnpm@9.8.0 with build as vitepress build. VitePress fails that build on a dead internal link unless ignoreDeadLinks is set, and the config does not set it, so links between posts are covered. External links are not: the 15 posts under posts/ carry 262 https:// links, most to github.com, vuejs.org, v3.vuejs.org, vitepress.dev and vitejs.dev, and some to repositories that have since moved or to archived documentation sites. There is no .github/ directory; the site deploys through vercel.json, which sets cleanUrls and a cache header for /assets/.
The agent adds .github/workflows/links.yml with two triggers: pull_request filtered to posts/**, index.md and the workflow file, and a weekly schedule. Its one step runs lycheeverse/lychee-action over posts/**/*.md and index.md. On a pull request it checks only the changed files, so a new post is checked without re-fetching every old link; on the schedule it checks everything with fail: false and a second step, peter-evans/create-issue-from-file, opens an issue from lychee's report, the pattern the action's own README shows, because a link that dies in a five-year-old post is a maintenance task, not a pull request failure.
A link checker on a real site needs an ignore list or it cries wolf, so the agent writes .lycheeignore from what it sees in the posts: twitter.com answers checkers with 403, chrome.google.com extension pages and marketplace.visualstudio.com return errors to non-browser clients, and jsdelivr CDN links to pinned versions are fine but slow. It passes --accept 200..=204,429 so a rate-limited answer is not a failure, and --max-concurrency low enough that github.com does not throttle the run. Redirected links, such as the vuejs/vue-next repository links that now land on vuejs/core, pass; lychee follows redirects and the agent leaves them for a later cleanup rather than editing posts.
Before opening the pull request the agent runs lychee in its sandbox over all 15 posts, reads the report, and sorts every failure into one of three bins: a real dead link, which it lists in the pull request description with the post and line; a site that blocks checkers, which goes into .lycheeignore with a comment naming the status it returned; and a transient error, which it retries. It fixes no post text, so the first scheduled run starts from the list in the pull request.
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 VitePress site. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, vercel.json and every file under posts/ first; note that VitePress already fails the build on dead internal links, so this is about external ones. Add .github/workflows/links.yml using lycheeverse/lychee-action: on pull requests that touch posts/**, index.md or the workflow, check only the changed Markdown files; on a weekly schedule, check every post with fail: false and open an issue from the report with peter-evans/create-issue-from-file, giving that job issues: write. Write a .lycheeignore for hosts that block checkers (twitter.com, chrome.google.com, marketplace.visualstudio.com) with a comment per line saying why, accept 429 as not-a-failure, and keep concurrency low so github.com does not throttle the run. Run lychee over all posts in your sandbox, sort each failure into dead link, blocked host or transient, and list the dead links with their post and line in the pull request description. Do not edit any post.",
"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 and .lycheeignore and changes nothing else. Its description has the lychee summary from the sandbox run and a table of links the agent judged dead, each with the post file and line, so the site's maintainers can fix or remove them in a separate change.
On the pull request the new check runs over the two added files and passes, since neither contains a link. From then on a pull request adding a post with a mistyped URL fails with the status lychee got, and the weekly run files an issue, through the second step with its issues: write permission, when something old breaks. VitePress's own build is untouched: vitepress build still fails on a dead internal link, and genFeed still writes the feed.
Before merging, a reviewer reads .lycheeignore line by line, because every entry is a host the site will never check again, and decides whether the weekly report should open an issue or post to a channel they already watch.
Run it on every new post
The workflow is the recurring part: each pull request that adds a post gets its links checked and the weekly schedule catches rot. The run on Rush is the one-time setup, and a team with several VitePress sites sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository name, so a retry does not open a second pull request.
Each run reads its own site: a documentation site with versioned folders gets a different paths filter, one with ignoreDeadLinks: true in its config gets internal links added to the check as well, and one that already has a workflow directory gets the new file in that directory's style.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Any developer can paste a lychee workflow. What takes the time is the first run: fetching a few hundred links, reading which failures are real, which hosts refuse bots, and which are rate limits, then writing an ignore list that is honest about each entry. The agent does that in its own sandbox with the real responses in front of it, and the pull request carries the sorted result rather than a workflow that fails on its first scheduled run for reasons nobody triaged.
The run keeps the commands and the lychee output, so a reviewer can check why a host was ignored. Several sites can get the same treatment at once, each with an ignore list that reflects its own links.
Frequently asked questions
Does VitePress not check links already?
It checks internal links: vitepress build fails on a link to a page that does not exist unless ignoreDeadLinks is set, and this config does not set it. It never fetches external URLs. lychee covers those.
Why run the full check on a schedule rather than on every pull request?
A full run fetches every link in every post and depends on a few hundred other servers. On a pull request that is slow and flaky for a change that touched one file. Checking only changed files on pull requests and everything weekly keeps the pull request signal clean and still catches links that die later.
What goes in .lycheeignore?
Hosts that answer checkers with an error regardless of the link's health, such as twitter.com and the Chrome Web Store, each with a comment saying what status the agent saw. The list is short on purpose; a reviewer should be able to read it in a minute.
Will it fail on links that redirect?
No. lychee follows redirects, so a link to a repository that was renamed passes as long as the destination answers. The agent notes such links in the pull request description if there are many, but does not treat them as failures.