What the agent does
The agent clones the repository into its own cloud sandbox and reads how the site is put together before adding anything. In a blog like 11ty/eleventy-base-blog, package.json pins @11ty/eleventy ^3.1.7 as an ES module project on Node 18 or newer (.nvmrc says 22), and eleventy.config.js sets content as the input folder with ../_includes and ../_data beside it. The same file registers two bundles with addBundle: a css bundle and a js bundle that collects the content of every <script> element on a page into one file under dist, with a comment in _includes/layouts/base.njk saying that a <script eleventy:ignore> tag is the way to keep one out of it. content/blog/blog.11tydata.js gives every file in content/blog the posts tag and the layouts/post.njk layout, and _data/metadata.js holds the site title, url, language and author. There is no comment system anywhere.
Giscus stores comments in GitHub Discussions, and its script tag needs four values the agent cannot make up: the repository as owner/name, its repoId, a discussion category and that category's categoryId. The agent adds a giscus object to _data/metadata.js with repo prefilled from the repository it cloned, repoId and categoryId left as empty strings behind a comment that says to copy them from the giscus.app configuration page once Discussions are on and the giscus app is installed, category set to Announcements as giscus recommends, mapping set to pathname, lang taken from metadata.language, theme set to preferred_color_scheme and reactions enabled.
The widget itself lives in a new _includes/comments.njk: a <section class="comments"> with a heading and the https://giscus.app/client.js script tag carrying the data- attributes from the metadata, crossorigin="anonymous" and async. The tag gets the eleventy:ignore attribute so the js bundle leaves the external script where it is instead of trying to inline it. post.njk includes the partial after the previous and next links, inside a condition that checks metadata.giscus.repoId is set and the post has not declared comments: false in its front matter. _data/eleventyDataSchema.js already validates draft with a zod schema and throws on a wrong type; the agent adds comments as an optional boolean to the same schema so a typo in front matter fails the build the way a bad draft does. A few lines in css/index.css give the section the same top margin as the metadata list.
Then it proves the change in the sandbox: npm install, npx @11ty/eleventy, and a check that _site/blog/firstpost/index.html contains the script tag with the data attributes while _site/about/index.html and the home page do not. It runs npm run build-ghpages as well, because that script passes --pathprefix=/eleventy-base-blog/ and the widget must not be affected by the HTML base plugin rewriting URLs; the giscus script is an absolute URL, so it is not. It changes no post, no feed and no other layout, and opens a pull request with the build output in its description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Giscus comments to this Eleventy blog. Read eleventy.config.js, the layouts in _includes/layouts and _data/metadata.js first. Keep the Giscus settings in the site metadata (repo, repoId, category, categoryId, mapping, lang, theme), prefill repo from this repository and leave the two ids empty with a comment on where to copy them from. Render the widget from a partial included at the end of the post layout only, let a post opt out with comments: false in its front matter and validate that field in the data schema, and make sure the JS bundle plugin leaves the external script tag alone. Build the site and confirm the widget appears on blog posts and nowhere else. Open a pull request.",
"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 on its own branch that adds _includes/comments.njk, changes _data/metadata.js, _includes/layouts/post.njk, _data/eleventyDataSchema.js and css/index.css, and touches nothing else. The description names the two values you still have to paste in, shows the lines of the built post page that carry the widget, and shows that the about page and the index do not.
The run's record keeps the npm install and both Eleventy builds with their output, so a reviewer can see that the build passed with the default path and with the GitHub Pages path prefix, and that the js bundle file in dist did not swallow the giscus tag.
Before merging, a reviewer turns on Discussions in the repository settings, installs the giscus GitHub app on that one repository, creates or picks an Announcements category, copies repoId and categoryId into _data/metadata.js, and decides whether pathname is the right mapping: it ties a thread to the URL path, which survives a domain move but not a slug change.
Run it on every blog you set up
Start it from a terminal with one POST /o/{org}/sessions carrying this body and the repository in resources, then close the laptop; the agent keeps working in its sandbox. When the pull request is up and you want a change, a follow-up with POST /o/{org}/sessions/{id}/messages wakes the parked sandbox where it left off: switch the mapping to title, add the widget to pages tagged notes as well, or move the section above the previous and next links.
If you maintain several Eleventy sites, a script can send one request per repository, each run in a sandbox of its own with its own pull request. Give each request a request_id, a UUID you keep per site, so running the script twice returns the run it already started instead of opening a second pull request on the same repository.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Adding a comment widget by hand is quick until the bundle plugin inlines the script, the widget shows up on the about page, or a post that should stay quiet cannot opt out. The agent reads the configuration first, puts the settings where the rest of the site data lives, validates the new front matter field like the existing one, and builds the site twice to show the widget lands only where it should.
The sandbox runs the real Eleventy build with the output kept in the run's record, so the pull request carries evidence rather than a promise. Nothing about your GitHub account is needed for the build: the two Discussions ids are the one part that stays with you, and the page says exactly where they go.
Frequently asked questions
Do I have to give the agent my GitHub Discussions ids?
No. The agent cannot read them and does not ask for them. It leaves repoId and categoryId empty in _data/metadata.js with a comment pointing at the giscus.app configuration page, and the post layout renders nothing until both are filled in, so merging the pull request early is safe.
Will comments show up on the about page or the home page?
No. The partial is included from layouts/post.njk only, which content/blog/blog.11tydata.js applies to files in the blog folder. Pages that use layouts/home.njk or layouts/base.njk directly are untouched, and the agent checks the built HTML of both to confirm it.
Does this work with the GitHub Pages build that uses a path prefix?
Yes. The giscus script is loaded from an absolute https://giscus.app URL, so the HTML base plugin does not rewrite it when npm run build-ghpages passes --pathprefix. The agent runs that build too and reports the result.
Can readers comment without a GitHub account?
They can read every thread without one, but posting a comment or a reaction requires signing in to GitHub through the widget, because each thread is a GitHub Discussion in your repository. If you need anonymous comments, Giscus is the wrong tool and the agent will say so if you ask.
How does a single post turn comments off?
Add comments: false to that post's front matter. The post layout checks the field before including the partial, and the data schema in _data/eleventyDataSchema.js rejects anything that is not a boolean, so comments: no fails the build instead of silently showing the widget.