What the agent does
The agent reads the theme before it adds a component, because a VitePress site with a custom theme has no default layout slots to hook into. In a blog laid out like vuejs/blog, .vitepress/theme/index.ts exports only Layout, and Layout.vue chooses between Home.vue, NotFound.vue and Article.vue by frontmatter.index and page.isNotFound. Article.vue renders the post through <Content> and a footer with next and previous links from posts.data.ts, a createContentLoader('posts/*.md') loader. .vitepress/config.ts sets cleanUrls: true, a head with Twitter meta and a Fathom script, and buildEnd: genFeed for the RSS file. Dark mode comes from Tailwind's dark: classes with no darkMode setting in postcss.config.js, so it follows prefers-color-scheme and there is no toggle to listen to. package.json pins pnpm@9.8.0, vitepress on the 1 line and vue on the 3 line, and there are sixteen posts under posts/.
Then it adds the component. @giscus/vue goes in as a dependency, and .vitepress/theme/Comments.vue wraps <Giscus> with repo, repoId, category, categoryId and mapping="pathname", strict="1", reactionsEnabled="1", inputPosition="top", theme="preferred_color_scheme", lang="en" and loading="lazy"; the ids come from the prompt, since they are issued by giscus.app once Discussions are enabled and the giscus app is installed on the repository, which the agent cannot do from a sandbox. mapping="pathname" works with cleanUrls, because the thread key is the post's path such as /posts/vitepress-1.0, which does not change if the title does. The component is rendered inside <ClientOnly>, since giscus registers a custom element that cannot run in VitePress's server render.
Article.vue gets <Comments> after <Content> and before the footer, behind v-if="frontmatter.comments !== false" from useData(), so a post can opt out with comments: false in its frontmatter; the agent documents that key in a comment in posts.data.ts rather than extending the Post interface, since the loader does not need it. The giscus theme is preferred_color_scheme because the site has no theme toggle; if one is added later, the component accepts a theme prop that follows it.
Then it builds and looks. pnpm install, pnpm build (vitepress build), and a check that .vitepress/dist/posts/vitepress-1.0.html contains no giscus markup, which is correct for a client-only component, followed by pnpm preview and a visit to that post in the sandbox browser to see the giscus-frame iframe load under the article, with a screenshot kept with the run. genFeed still runs at buildEnd and feed.rss is unchanged, which the agent checks by diffing it against a build from main.
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 VitePress blog with a custom theme. Read package.json, .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/index.ts, Layout.vue, Article.vue, Home.vue, posts.data.ts, postcss.config.js and the frontmatter of two posts first. Add @giscus/vue and a Comments.vue component in the theme that renders Giscus inside ClientOnly with repo your-org/your-blog, repoId R_XXXX, category Announcements, categoryId DIC_XXXX, mapping pathname, strict on, reactions on, input position top, theme preferred_color_scheme, lang en and lazy loading. Render it in Article.vue after the content unless the post's frontmatter sets comments to false. Run pnpm build, confirm the built post HTML has no giscus markup, then run pnpm preview and open one post in the browser to confirm the giscus iframe loads, with a screenshot. Confirm feed.rss is unchanged. Open a pull request with the output and the screenshot.",
"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
The pull request changes package.json, pnpm-lock.yaml and .vitepress/theme/Article.vue, and adds .vitepress/theme/Comments.vue. Its description shows the build output, the screenshot of a post with the thread loaded, the empty feed.rss diff, and the frontmatter key a post uses to opt out.
There is no workflow in the repository, so no check runs on the pull request; vercel.json suggests Vercel builds the site, and its preview deployment is where a reviewer sees the thread on the real domain, which is also where giscus's origin check matters.
Before merging, a reviewer confirms the repoId and categoryId match the giscus.app configuration for the repository, decides whether the home page or the 404 page should ever show a thread (they do not here, since only Article.vue renders it), and decides whether strict matching is wanted, which binds each thread to the page's exact path.
Run it on every new blog or docs site
A team that runs a VitePress site per product starts one run per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources, that site's giscus ids in input, and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own theme: a site on the default theme gets the component in the doc-after layout slot through enhanceApp, and one with an appearance toggle gets the giscus theme bound to isDark from useData().
After the merge, an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request adds a post under posts/, say whether comments will render on it and whether the frontmatter opts out" catches announcement posts that should stay quiet. The trigger adds the pull request after the prompt; only pushes by an owner, member or collaborator fire 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?
The snippet giscus gives you is five lines; fitting it to a custom VitePress theme is the work: finding the component that renders a post, keeping the custom element out of the server render, matching the site's colour scheme, and choosing a thread key that survives a title change. The agent reads the theme at its installed version, makes those choices from what it finds, and builds the site to show the thread lands on posts and nowhere else.
In its own sandbox the agent runs the build and the preview and opens a post in a real browser, so the pull request carries a screenshot of the loaded thread rather than a promise. For a team with several sites, each gets its own run and its own pull request, fitted to its own theme.
Frequently asked questions
Why ClientOnly?
VitePress renders each page to static HTML at build time, and @giscus/vue registers the giscus-widget custom element, which needs a browser. Wrapping it in <ClientOnly> leaves it out of the server render and mounts it on the client, which is why the built HTML has no giscus markup and the check is done in a browser.
Does the thread follow dark mode?
This theme has no toggle; dark styles come from Tailwind's media strategy. theme="preferred_color_scheme" makes giscus follow the same system setting. A site with a toggle passes a computed theme prop instead, and the agent says so in the component.
What do I need to set up before running this?
Discussions enabled on the repository, the giscus GitHub app installed on it, and the ids from giscus.app for the repository and the category. Those steps need a person on github.com; the run takes the ids in its prompt.
Will the RSS feed change?
No. genFeed renders posts with createContentLoader at buildEnd, independent of the theme components, and the agent diffs feed.rss against a build from main to show it.
More VitePress jobs
The same job on other stacks
- Add Giscus Comments to a Zola Blog (Zola)
- Add Giscus Comments to an Astro Blog (Astro)
- Add Giscus Comments to a Docusaurus Blog (Docusaurus)