What the agent does
The agent reads the theme's own layout before it writes anything. In an Astro 7 blog shaped like satnaing/astro-paper, posts render through src/pages/posts/[...slug]/index.astro: getStaticPaths builds one page per entry of the posts collection defined in src/content.config.ts, the body renders as
Configuration goes where the theme keeps it. astro-paper.config.ts is the user-facing file, typed by defineAstroPaperConfig in src/types/config.ts, and src/config.ts applies defaults into a Required features object that components import as config. The agent adds a comments entry to FeaturesConfig with the values the Giscus app issues, repo, repoId, category, categoryId and a mapping of pathname, plus an enabled flag defaulting to false, so a site that never fills it in builds exactly as before. The repository ships a post, src/content/posts/how-to-integrate-giscus-comments.md, that explains the setup; it names a PostDetails.astro file that no longer exists in this version and proposes a React component, and the agent notes both rather than following it blindly, because package.json has no React and no @astrojs/react, and adding a framework for one iframe is the wrong trade.
The hard part is the theme. Layout.astro sets data-theme on the html element in an inline script before paint, and src/scripts/theme.ts flips it when #theme-btn is clicked, persists it in localStorage under theme, and re-runs on astro:after-swap because the layout uses ClientRouter view transitions. The agent writes src/components/Comments.astro that injects the giscus.app client script with data-theme set from the current attribute, then posts a setConfig message to the giscus iframe whenever the attribute changes, through a MutationObserver on the html element. Because the post page's own inline script is marked data-astro-rerun, the agent does the same, so a view-transition navigation from one post to the next mounts a fresh comments block for the new pathname instead of showing the previous post's thread.
It then proves the build, with the repo's own commands. pnpm-workspace.yaml and pnpm-lock.yaml make it pnpm; .github/workflows/ci.yml pins pnpm 11.3.0 on Node 24 and runs pnpm run lint, pnpm run format:check and pnpm run build inside a three-minute timeout. The agent runs the same three: eslint with the no-console rule set to error in eslint.config.js, prettier with the astro and tailwindcss plugins from .prettierrc, and the build, which starts with astro check so the new config type has to agree with what astro-paper.config.ts contains. It previews the built site and screenshots a post page in both themes to confirm the block appears and the page layout does not shift, though the iframe itself only loads once the owner has filled in the repo values.
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 Astro blog. Read package.json, astro.config.ts, astro-paper.config.ts, src/config.ts, src/types/config.ts, src/content.config.ts, src/layouts/Layout.astro, src/scripts/theme.ts, src/pages/posts/[...slug]/index.astro and src/content/posts/how-to-integrate-giscus-comments.md first. Do not add React or any framework integration; use the plain giscus client script in a new src/components/Comments.astro. Add a comments feature to the config types and astro-paper.config.ts with repo, repoId, category, categoryId, mapping and an enabled flag that defaults to false, leaving placeholder values and a comment that says where to get them from giscus.app. Render the block below ShareLinks and above AdjacentPostNav on the post page, outside the pagefind body. Make the giscus theme follow the data-theme attribute on the html element, including after a view transition and after the theme button is clicked. Run pnpm install --frozen-lockfile, pnpm run lint, pnpm run format:check and pnpm run build as ci.yml does, fix what they report, and open a pull request that lists the files, says what the owner must fill in, and quotes the build output.",
"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 src/components/Comments.astro, extends FeaturesConfig in src/types/config.ts and the defaults in src/config.ts, adds a disabled comments block with placeholders to astro-paper.config.ts, and edits src/pages/posts/[...slug]/index.astro to render the component between the share links and the adjacent-post navigation. No dependency is added to package.json and pnpm-lock.yaml is unchanged.
The description explains the choices: why the script tag and not the React component the bundled post suggests, how the theme stays in sync through the data-theme attribute and the astro:after-swap event, and why the block sits outside data-pagefind-body. It quotes the lint, format and build output from the sandbox and lists the four values the owner has to paste from giscus.app, after installing the Giscus app and turning on Discussions for a public repository, which no agent can do on the owner's behalf.
Before merging, a reviewer checks that the component renders nothing when enabled is false, that the theme message names the same light and dark giscus themes the site's palette suits, and that the component does not land inside the pagefind body. Then they fill in the config on the branch, run pnpm run dev, and watch the thread load on one post.
Run it on every theme feature request
Start one run per feature the blog's owner wants added, with this request and the repository in resources. The sandbox keeps its branch and its built dist directory between turns, so when the owner has created the Discussions category and has the repoId and categoryId, a follow-up on the same session wakes the parked sandbox, fills in astro-paper.config.ts and pushes to the same pull request instead of starting over.
Give the key a webhook URL and Rush POSTs run.completed or run.failed with data.session_url when each turn ends, so a small script can post the pull request link where the owner reads. Several blogs built on the same theme can get the feature at once, each in its own sandbox, up to the key's max_concurrent limit of 4 by default.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The slow part of this job is not the script tag, it is the theme and the build. Checking that comments switch with the theme button, survive a view transition and stay out of the search index means running pnpm run build with astro check and pagefind, previewing, and clicking through posts in both themes, which on a laptop competes with whatever else is open. The agent does it in its own sandbox with a browser, and the screenshots land on the session.
The record stays with the result. The transcript holds every file the agent read, the lint, format and build commands with their output, and the preview checks, so a reviewer who did not watch can see why the React path was declined and what the owner still has to fill in. Nothing was pushed to the owner's main branch, only a branch with a pull request.
Frequently asked questions
Can the agent finish the Giscus setup on GitHub for me?
No. Giscus needs the repository to be public, the Discussions feature turned on and the Giscus GitHub App installed, and then issues a repoId and categoryId from giscus.app. Those are steps a repository owner takes while signed in to GitHub. The agent leaves the config disabled with placeholders and says exactly which four values to paste.
Will it add React to my Astro site?
Not for this. The theme's own how-to post proposes a React wrapper, but package.json has no React and the prompt forbids a framework integration. The plain giscus client script plus a short inline script that relays theme changes to the iframe does the same job with no new dependency.
Does it work with the light and dark toggle?
Yes. The theme is a data-theme attribute on the html element, set before paint by the inline script in Layout.astro and flipped by src/scripts/theme.ts. The component watches that attribute and posts the matching theme to the giscus iframe, and it re-mounts after astro:after-swap so view transitions between posts load the right thread.
Can comments be turned off for one post?
Ask for it in the prompt or in a follow-up. The posts collection schema in src/content.config.ts already carries flags like hideEditPost, and a hideComments boolean follows the same pattern, read by the post page before it renders the component.
Will the comments show up in site search?
No. The build runs pagefind over dist and indexes only elements inside data-pagefind-body. The component renders outside that element, or carries data-pagefind-ignore, so other people's comments never appear as search results for your posts.
More Astro jobs
The same job on other stacks
- Add Giscus Comments to a Docusaurus Blog (Docusaurus)
- Add Giscus Comments to an Eleventy Blog (Eleventy)
- Add Giscus Comments to a Gatsby Blog (Gatsby)