What the agent does
The agent reads the site's build before adding a data source. In a site like 11ty/eleventy-base-blog, package.json at version 9.0.0 is an ES module on @11ty/eleventy 3.1.7 with the image, navigation, RSS and syntax highlight plugins, Luxon and Zod, and .nvmrc pins Node 22. eleventy.config.js sets content as the input directory with _includes and _data beside it and _site as output, drops drafts in a build, bundles CSS and JS per page, serves an Atom feed at /feed/feed.xml with https://example.com/ as its base, and transforms images. _data/metadata.js holds the title, url, language and author. _includes/layouts/post.njk prints the title, a post-metadata list with the date and tags, the content, and previous and next links from getPreviousCollectionItem; base.njk adds the feed link in the head and inlines the CSS bundle. Posts under content/blog/ get the posts tag from blog.11tydata.js. The sample GitHub Pages workflow already caches ./.cache under an eleventy-fetch-cache key, a directory nothing in the repository writes to yet. No page carries h-entry markup, so a reply to a post from another site has nothing to parse, and nothing on the site shows the replies that arrive.
The agent adds @11ty/eleventy-fetch as a dev dependency and writes _data/webmentions.js, which reads the domain from metadata.url, takes the API token from the WEBMENTION_IO_TOKEN environment variable, and fetches https://webmention.io/api/mentions.jf2 for that domain with a one-day cache in .cache, so a build repeats the request at most once a day and the Pages workflow's cache carries it between runs. With no token set the file logs one line and returns an empty children list, which keeps npm run build working on a fork or a first checkout. In _config/filters.js it adds webmentionsForUrl, which matches each mention's wm-target against the page's full URL with and without a trailing slash and sorts by published, and webmentionsByType, which groups by wm-property into likes, reposts, replies and mentions.
In _includes/layouts/post.njk it adds h-entry to the article wrapper, p-name on the title, dt-published on the existing time, e-content around the content and a p-author h-card with the author's name and URL from metadata.js, so other sites' parsers find the post's author and date. Below the previous and next links it includes a new _includes/webmentions.njk: a count line for likes and reposts with the authors' photos, then each reply with the author's name linked to their site, the published date through the existing readableDate filter, and the content.text of the reply, escaped. base.njk gets rel="webmention" and rel="pingback" links in the head pointing at webmention.io for the domain. Styles for the block go in css/index.css next to the links-nextprev rules, and .cache/ is confirmed ignored by Git.
The build is the test. The agent runs npm run build once with the variable unset and once with a token, and both produce _site with the post layout rendering the block or an empty section. A node --test file for the two filters feeds them a fixture of jf2 entries and checks the URL matching, the trailing-slash case and the grouping; package.json gains a test script that runs it. The pull request describes the webmention.io setup the reader does once: sign in with the site's domain, copy the token, and set it as a secret in the deploy environment.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add webmentions to this Eleventy blog using webmention.io. Read package.json, eleventy.config.js, _data/metadata.js, _config/filters.js, _includes/layouts/base.njk, _includes/layouts/post.njk, content/blog/blog.11tydata.js, css/index.css, .gitignore and .github/workflows/gh-pages.yml.sample first. Add @11ty/eleventy-fetch and a _data/webmentions.js that fetches the mentions.jf2 feed for the domain in metadata.url with the token from the WEBMENTION_IO_TOKEN environment variable, caches for one day in .cache, and returns an empty list when the token is unset. Add filters that select mentions for a page URL with and without a trailing slash and group them by wm-property. Add h-entry, p-name, dt-published, e-content and a p-author h-card to the post layout, include a webmentions block after the previous and next links showing likes and reposts with author photos and replies with author, date and text, add webmention and pingback link elements to the head, and style the block in css/index.css. Make sure .cache is ignored. Run npm run build with and without the variable, write a node --test file for the filters with a test script, and open a pull request that explains the one-time webmention.io setup.",
"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 _data/webmentions.js, _includes/webmentions.njk and a filter test, edits _config/filters.js, _includes/layouts/post.njk, _includes/layouts/base.njk, css/index.css and package.json, and adds the dependency to the lockfile. The description names the environment variable, the one-day cache, the microformats added to each post and the one-time webmention.io setup.
The run's record keeps both npm run build logs, the one without a token showing the skip line and the one with a token showing the fetch and cache write, plus the node --test output with each filter case named, so a reviewer can see the build does not depend on the secret and the URL matching handles the trailing slash the site's vercel.json adds.
Before merging, a reviewer opens a built post in _site, confirms the h-entry markup with a microformats parser, sets the token in the deploy environment and triggers a build, and checks that a known reply to an existing post renders under it with the author's name and date.
Run it on every Linear issue labelled community
In the console, an automation with a linear trigger on linear.issue.labeled and the label community starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so an issue asking for likes to be hidden or for a reply form carries that request itself and the prompt stays fixed. Changes made by an app integration never fire it, and the automation's max_runs_per_hour bounds a burst of labelling.
From your own server, the same job is one POST /o/{org}/sessions per issue, with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL beside it so Rush reads the issue through your Linear connection. A webhook_url on the API key receives run.completed or run.failed for every run that key starts, with the session_url to read the pull request link from.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Webmentions touch three layers at once, a build-time fetch, a data filter and a layout, and each fails quietly: a fetch that throws when the token is missing breaks every fork's build, a target match that ignores the trailing slash shows no replies on a site that adds one, an h-entry without dt-published gets parsed with no date. The agent runs the real build twice in its own sandbox and tests the filters against fixture data, which is the only way to see those failures before deploy.
The commands and their output stay with the run, so the pull request can point at the build log that ran without the secret and at the filter test that covers the slash, and a reviewer checks the claim against the record rather than against the description.
Frequently asked questions
Does the build need the webmention.io token?
No. Without WEBMENTION_IO_TOKEN the data file returns an empty list and logs that it skipped the fetch, so forks, pull request previews and a first checkout build cleanly. The token is set once in the deploy environment, and the one-day cache in .cache keeps builds from hitting the API every time.
Will my old posts receive webmentions?
Receiving needs the rel="webmention" link in the head and the h-entry markup on the post, both of which the layout now provides for every post, old and new. Replies sent before the endpoint existed were never delivered and cannot be recovered.
Does this send webmentions when I link to other sites?
No. Sending is a separate step, a request to each linked site's endpoint after a post is published, and it is not in this change. The pull request notes it as a follow-up, with the Atom feed at /feed/feed.xml as the input a sender would read.
What about the trailing slash?
The site's vercel.json sets trailingSlash to true and Eleventy writes directory URLs, so a mention's target may arrive with or without the slash. The webmentionsForUrl filter compares both forms, and the test covers that case.