What the agent does
The agent reads how the site is built before adding a feed, because the feed has to come from the same collection and the same URLs as the pages. In a site started from Starlight's examples/basics, package.json depends on @astrojs/starlight ^0.42.7, astro ^7.2.10 and sharp, with dev, build and preview scripts. astro.config.mjs registers the starlight integration with the title My Docs, one GitHub social link and a sidebar of a Guides group pointing at guides/example and a Reference group autogenerated from the reference directory; it sets no site. src/content.config.ts defines one collection, docs, with docsLoader() and docsSchema(), whose frontmatter is a required title, an optional description, an optional lastUpdated that is a date or a boolean, and draft, which defaults to false. The content is index.mdx, a splash page, plus guides/example.md and reference/example.md. No src/pages directory exists, and nothing in the repository mentions a feed.
The feed is an Astro endpoint, which Starlight allows beside its own routes through the src/pages/ directory. The agent installs @astrojs/rss and writes src/pages/rss.xml.ts, whose GET calls getCollection('docs'), drops the entry whose id is index because the splash page is not an article, drops any entry with draft set, and maps the rest to items with title from data.title, description from data.description when there is one, and link built from the entry's id with a trailing slash, which is the path Starlight serves the page at. @astrojs/rss needs site, so the agent adds site to defineConfig with a placeholder address the pull request tells the reader to replace, and rss() takes it from context.site so there is one place to change.
A feed without dates is a list, not a feed, and the schema makes lastUpdated optional, so the agent dates each item the way Starlight dates its own footer: from Git. For an entry whose lastUpdated is a date, that is pubDate; for the rest, the endpoint runs git log -1 --format=%cI on the entry's filePath with execFileSync and parses the result, falling back to the build time when the repository has no history for the file, which is what happens on a platform that builds from a shallow clone, and the pull request names that case. Items are sorted newest first. The endpoint also sets customData with a <language> element taken from the site's locale.
Readers find a feed through the page head, so the agent adds a head entry to the Starlight config: a link tag with rel="alternate", type="application/rss+xml", the site title and href="/rss.xml", which Starlight writes into every page as is. In the sandbox it runs npm install and npm run build, checks that dist/rss.xml exists and parses as XML with one item per non-splash page, each link beginning with the configured site, runs npm run preview and fetches /rss.xml and /guides/example/ to confirm the item links resolve to real pages and the head carries the alternate link, and opens the pull request with the generated feed pasted in.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add an RSS feed to this Starlight site. Read package.json, astro.config.mjs, src/content.config.ts, tsconfig.json and every file under src/content/docs first. Install @astrojs/rss and write src/pages/rss.xml.ts whose GET reads the docs collection with getCollection, skips the entry with id index and any entry with draft set, and maps the rest to items with the page title, its description when present, and a link made from the entry id with a trailing slash. Use the entry's lastUpdated frontmatter as pubDate when it is a date; otherwise read the file's last commit date from Git with git log -1 --format=%cI on its filePath, and fall back to the build time when Git has no history, saying so in the pull request. Sort items newest first and set a language element in customData. Add site to defineConfig in astro.config.mjs with a placeholder the README tells the reader to replace, and add a head entry to the starlight config with a link tag rel alternate, type application/rss+xml, the site title and href /rss.xml. Run npm install and npm run build, confirm dist/rss.xml parses as XML with one item per non-splash page and links that start with site, run npm run preview and fetch /rss.xml and one page to confirm the links resolve and the head has the alternate link, then open a pull request that pastes the feed.",
"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 src/pages/rss.xml.ts, changes astro.config.mjs for site and the head entry, adds @astrojs/rss to package.json and the lockfile, and adds a note to README.md on replacing the placeholder site address. The description pastes the generated rss.xml from the build, with one <item> per page under guides and reference, each dated from Git and linked under the configured site, and the <link rel="alternate"> line as it appears in a built page's head.
The run's record holds npm install, the full astro build output, the XML parse of the feed, and the preview requests to the feed and a page. The Markdown and MDX content is untouched, and no page's frontmatter changes; pages that want a fixed date can set lastUpdated and the endpoint prefers it.
Before merging, a reviewer sets the real site, decides whether the feed should list every page or only a guides subtree, which is a one-line filter on the entry id, and whether lastUpdated: true should also be turned on in the Starlight config so the footer and the feed agree on dates.
Run it on every new docs site
A team with several Starlight sites starts one run per repository from its own server: one POST /o/{org}/sessions each, with that 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 a second pull request. Each run reads that site's own collection and locales, so a site with i18n configured gets one feed per locale root and a site with a site already set keeps it.
Afterwards, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "build the site and compare dist/rss.xml with the one on main; comment with the items added, removed or redated" shows reviewers what subscribers will see before a docs change merges. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A feed endpoint is a few lines, and the ways it goes wrong are only visible after a build: a missing site makes rss() throw, a splash page shows up as an article, item links point at /index/, and every item carries the same date because nothing set one. The agent builds the site in its own sandbox, parses the feed it produced, requests the pages the items link to, and reads the head of a built page, so each of those is checked before review.
The sandbox keeps the build output and the generated feed with the run, and the pull request pastes them. For a team with many Starlight sites, each gets its own run and its own pull request, with links and dates taken from that site's content and Git history rather than copied from another.
Frequently asked questions
Why does the feed need site in astro.config.mjs?
Because feed items must carry absolute links, and @astrojs/rss builds them from context.site, which is only set when defineConfig has site. The example config has none, so the agent adds a placeholder and says in the README and the pull request to replace it. The build check confirms every item link starts with that value.
Where do the dates come from?
From the page's lastUpdated frontmatter when it is a date, and otherwise from the last commit that touched the file, read with git log on the entry's filePath at build time, which is how Starlight dates its own footer. On a shallow clone with no history the endpoint falls back to the build time; the pull request says so and names the fix of a full clone or explicit frontmatter dates.
Will the splash page or drafts appear in the feed?
No. The entry with id index is skipped because it is the landing page, and entries with draft set are skipped, matching what Starlight leaves out of a production build. A reviewer who wants only one directory in the feed changes the filter on the entry id.
Does this change how Starlight renders pages?
No. The endpoint lives in src/pages, which Starlight leaves alone, and the only change to the rendered pages is one link tag in the head from the head config entry, which Starlight writes into every page unchanged. The content collection, sidebar and components are as they were.
More Starlight jobs
The same job on other stacks
- Add an RSS Feed to a SvelteKit App (SvelteKit)
- Add an RSS Feed to a Wagtail Blog (Wagtail)
- Add an RSS Feed to a Contentlayer Blog (Contentlayer)