What the agent does
The agent reads the site's config and content before it changes anything, because a sitemap is only right if its hostname and dates are. In a blog laid out like vuejs/blog, .vitepress/config.ts sets title, description, cleanUrls: true, a head with Twitter meta tags, a favicon and an analytics script, and a buildEnd hook, genFeed from .vitepress/genFeed.ts, which loads posts/*.md with createContentLoader, sorts them by their frontmatter date and writes feed.rss into the build's outDir with the base URL hard-coded as a constant. There is no sitemap key. package.json runs vitepress build and pins vitepress on a caret range that pnpm-lock.yaml resolves to 1.3.4, with gray-matter and feed among the dev dependencies and pnpm named in packageManager. public/ holds favicon.ico, logo.svg and two images, and no robots.txt. The posts are Markdown files in posts/, each with title, date and author in frontmatter, and vercel.json only sets cleanUrls and a cache header for /assets/.
VitePress generates sitemap.xml itself once sitemap.hostname is set, so the first change is one line in config.ts: sitemap: { hostname: 'https://blog.vuejs.org' }, the same URL genFeed.ts already uses, which the agent lifts into a shared constant so the feed and the sitemap cannot drift. With cleanUrls on, the URLs VitePress writes have no .html, matching what Vercel serves. The <lastmod> entries are the part that takes thought. VitePress fills them from lastUpdated, which reads git history at build time, and a blog's meaning of "last modified" is the post's date, not its last typo fix, so the agent uses the transformItems hook instead: it reads each post's frontmatter with gray-matter, which is already installed, and sets lastmod on the matching item from date, leaving the index page without one.
Then it adds public/robots.txt with Allow: / and a Sitemap: line pointing at the sitemap's full URL, so crawlers find it without being told, and checks that nothing else in public/ or vercel.json already answers that path.
To verify, the agent runs pnpm install --frozen-lockfile and pnpm build in its sandbox, which runs genFeed and the sitemap writer in the same build, then reads .vitepress/dist/sitemap.xml and .vitepress/dist/robots.txt. It checks that every file in posts/ has an entry, that each entry's lastmod matches that post's frontmatter date, that the index is present, that no URL ends in .html, and that feed.rss still lists the same posts in the same order, and pastes the sitemap into the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a sitemap to this VitePress blog. Read .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/posts.data.ts, package.json, vercel.json, the public directory and the frontmatter of every file in posts first. Set sitemap.hostname in config.ts to the base URL genFeed.ts already uses, moved into one shared constant. Use the transformItems hook to set each post's lastmod from its frontmatter date with gray-matter, which is already a dev dependency, and leave the index without one. Add public/robots.txt with a Sitemap line. Run pnpm install --frozen-lockfile and pnpm build, read .vitepress/dist/sitemap.xml, check that every post is present with the right lastmod, that no URL ends in .html and that feed.rss is unchanged, and open a pull request with the generated sitemap in the description.",
"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 changes .vitepress/config.ts and .vitepress/genFeed.ts, and adds public/robots.txt. Its description pastes the generated sitemap.xml with one entry per post and the index, shows the lastmod of three posts beside their frontmatter dates, and quotes the pnpm build output.
The repository has no workflow, so no check runs on the pull request; Vercel builds the branch as it builds any other, and the description names the two paths to open on the preview, /sitemap.xml and /robots.txt. The run's record keeps the install and the build.
Before merging, a reviewer decides whether the index page should carry a lastmod equal to the newest post's date, whether changefreq or priority are worth setting, and whether lastUpdated should be turned on as well for the <lastmod> of pages that are not posts.
Run it on every new site launched
A team that runs 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's full name, so a retried call returns the run already started rather than opening a second pull request. Each run reads its own config: a site with base set gets the base appended to hostname as VitePress requires, a docs site with no dated content gets lastUpdated instead of a frontmatter hook, and a site whose config.ts already has sitemap gets a comment that nothing is needed.
Afterwards, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds a Markdown file outside posts/, check whether the sitemap's transformItems hook still gives it a sensible lastmod and comment if not" catches the page that the frontmatter rule does not cover. Automation runs are read-only, so the comment is all it posts.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A sitemap is a one-line option, and the one line is where it goes wrong: a hostname that differs from the feed's, a lastmod that changes every time someone fixes a typo in an old post, a URL with .html on a site that serves clean URLs. The agent reads the feed generator and the Vercel config so the sitemap agrees with both, and builds the site in its own sandbox to read the file that would ship.
The build output and the generated sitemap.xml stay with the run and are pasted into the pull request, so the review is of the file itself rather than of a config change that looks right. Several sites get the same change at once, each built on its own.
Frequently asked questions
Why not just turn on lastUpdated?
Because lastUpdated reads the last git commit that touched each file, so fixing a typo in a post from years ago would make it the newest entry in the sitemap. For a blog, the post's frontmatter date is the date that means something, and the transformItems hook sets lastmod from it. The description names lastUpdated as the right choice for pages that are not posts.
Does this change the RSS feed?
Only by moving the base URL into a constant that genFeed.ts and the sitemap share, so they cannot disagree. The agent checks that feed.rss after the build lists the same posts in the same order as before, and pastes the diff, which should be empty.
Will the URLs match what Vercel serves?
Yes. cleanUrls: true in config.ts makes VitePress write URLs without .html, and vercel.json sets the same option, so the sitemap's /posts/<slug> entries are the addresses a visitor sees. The agent checks that no entry ends in .html after the build.
Why add robots.txt?
Because a crawler that has never been told the sitemap's address finds it through the Sitemap: line in robots.txt, and public/ has no such file. The agent adds one with Allow: / so nothing is blocked by accident.
More VitePress jobs
The same job on other stacks
- Add a Sitemap to an Astro Blog (Astro)
- Add a Sitemap to a Gatsby Blog (Gatsby)
- Add a Sitemap to a Jekyll Site (Jekyll)