What the agent does
The agent reads how the site already produces machine-readable copies of itself, because llms.txt is one more of them. In a blog like satnaing/astro-paper, package.json is on Astro 7.4.5 with @astrojs/rss and @astrojs/sitemap, and src/pages/ holds two endpoints that are the pattern to follow: rss.xml.ts, which exports a GET that calls getCollection("posts"), sorts with getSortedPosts and builds each item's link with getPostUrl, and robots.txt.ts, which returns plain text with the sitemap URL built from site. The posts collection in src/content.config.ts uses the glob loader over src/content/posts and gives every entry a title, description, pubDatetime, optional modDatetime, tags and a draft flag; a second pages collection holds about.md. astro-paper.config.ts sets the site title, description and URL that src/config.ts resolves with defaults.
It writes src/pages/llms.txt.ts as a third endpoint. The body follows the llms.txt layout: an H1 with the site title, a blockquote with the site description, a ## Posts section with one line per post, - [title](absolute URL): description, and a ## Pages section with the about page. The post list comes from getSortedPosts, not from getCollection alone, because postFilter in src/utils/postFilter.ts is where drafts are dropped and where a post dated after the build day in the site's timezone is held back; the RSS feed uses the same function, and the file must not list a post the site will not serve. URLs are made absolute with new URL(getPostUrl(id, filePath), Astro.site) the way Layout.astro builds its canonical link, so a base or locale prefix in the config is honoured.
src/pages/llms-full.txt.ts carries the text. For each post the agent writes the title, date and tags as a header and then the entry's body, the raw source the glob loader keeps on each entry. For a .md post that is the Markdown as written. For .mdx posts, of which this theme has several, the body carries component imports and JSX, so the agent writes the Markdown ones in full and lists the MDX ones with their link and description only, and says so in the pull request, because rendering MDX to text would mean a renderer the site does not have. The release notes under src/content/posts/_releases/ start with an underscore, which the loader's [^_]* pattern already excludes, so they stay out of both files.
Then it builds the way the repository does. The build script runs astro check && astro build && pagefind --site dist && node copy-pagefind.mjs, so a type error in the new endpoints stops the build before anything is written; the agent runs it, reads back dist/llms.txt and dist/llms-full.txt, and checks that the number of entries equals the number of posts the index and the feed list. It runs pnpm run lint and pnpm run format:check, the two commands .github/workflows/ci.yml runs before the build, since Prettier with prettier-plugin-astro is strict about the new files.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add llms.txt and llms-full.txt to this Astro blog. Read package.json, astro.config.ts, the site config file, src/content.config.ts, src/pages/rss.xml.ts, src/pages/robots.txt.ts and the utilities under src/utils first. Write src/pages/llms.txt.ts as a GET endpoint: an H1 with the site title, a blockquote with the site description, a Posts section with one line per post in the form - [title](absolute url): description, and a Pages section for any pages collection. Take the posts from the same sorted and filtered list the RSS feed uses so drafts and scheduled posts are left out, and build absolute URLs the way the layout builds its canonical URL. Write src/pages/llms-full.txt.ts with each post's title, date, tags and raw body; where a post is MDX and its body carries imports or JSX, list it with its link and description only and say so in the pull request. Run the build script, the lint and format check scripts, read back the two files from dist and confirm the post count matches the index, paste the output in the pull request and open it.",
"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
A pull request that adds two files under src/pages/ and changes nothing else: no config change, no new dependency, no edit to the layout. The description quotes the build output with the two new routes in the list of generated files, the first lines of dist/llms.txt, and the count of posts in it beside the count the index page renders.
A reviewer opens dist/llms.txt from the build and checks the description lines read well out of context, since they are what a model sees first, and checks that no draft is listed; the example draft under src/content/posts/examples/ is the quick test. They then decide whether llms-full.txt should carry the MDX posts too, which is a question of adding a renderer, not of this change.
Nothing links to the files yet. The pull request suggests a <link> in Layout.astro only if the reviewer wants one; the files answer at their paths either way.
Run it on every new blog repository
A company with several Astro sites runs this once per repository rather than by hand. A short script on your server lists the repositories and sends one POST /o/{org}/sessions per site with this body and that repository in resources. Give each request a request_id, a UUID made with UUID v5 from the repository name, so a retried run of the script returns the session it already started instead of opening a second pull request. Set a webhook_url on the key from the console's Developers page and each run.completed event names the session; read the pull request from it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The two files are small; what takes care is matching the site's own rules, which post is public, what its URL is with a base path or locale, and what an MDX body looks like as text. The agent reads those rules from postFilter.ts, getPostPaths.ts and the content config and then runs the build in its own sandbox with the exact Astro and Pagefind versions in your lockfile, so the file it describes is the file the build wrote.
The build output, the lint run and the read-back of dist/llms.txt stay in the run's transcript at GET /o/{org}/sessions/{id}/messages, and the two new files are listed with their content at GET /o/{org}/p/{project}/sessions/{id}/changes. A reviewer who wants to see what a model would fetch reads it there before the branch is deployed.
Frequently asked questions
Will drafts or scheduled posts appear in llms.txt?
No. The endpoint takes its list from getSortedPosts, which runs postFilter: drafts are always dropped, and in a production build a post whose publish day is after the build day in the site's timezone is held back. The RSS feed and the index use the same function, so the three stay in step.
Why are MDX posts listed without their text?
An entry's body is the raw source. For .md that is Markdown; for .mdx it includes import lines and components that mean nothing as plain text. The agent writes Markdown bodies in full and gives MDX posts a link and description, and notes in the pull request that rendering them would need a separate step.
Does it need a new Astro integration or package?
No. Both files are endpoints under src/pages/, the same mechanism as rss.xml.ts and robots.txt.ts in this theme, and build with astro build as they are. An integration would add a dependency for what two short files do.
What if the site uses a base path or a locale prefix?
URLs are built with getPostUrl, which goes through getRelativeLocaleUrl and the configured base, and then made absolute against Astro.site, the same way Layout.astro builds the canonical link. A site served under a subpath gets correct links without any change to the endpoint.