What the agent does
The agent first reads what the site already puts in <head> and what each post knows about itself. In a blog laid out like vuejs/blog, .vitepress/config.ts sets a site-wide head with three Twitter metas, twitter:site as @vuejs, twitter:card as summary and twitter:image pointing at the Vue logo, plus a favicon link and a Fathom script, and nothing per page: no og:title, og:description, og:url or og:type anywhere. The posts in posts/ carry title, date, author, gravatar and twitter in their front matter and no description, so a share card today shows the site title and a generic summary for every one of the fifteen posts. cleanUrls: true in the config and vercel.json means a post's public address is https://blog.vuejs.org/posts/vue-3-5, with no .html, which matters for og:url. .vitepress/genFeed.ts already derives each post's excerpt and absolute link for feed.rss, so the agent reuses those rules rather than inventing new ones.
The change goes into config.ts as a transformPageData hook, the VitePress build hook that runs once per page with the page's front matter and relativePath, and lets the hook push entries onto pageData.frontmatter.head. For a page under posts/, the agent pushes og:type as article, og:title from frontmatter.title, og:url from the site origin plus the relativePath with its .md removed, article:published_time from frontmatter.date, article:author from frontmatter.author, and twitter:creator from frontmatter.twitter when the post has one. For the description it reads the post's own file with gray-matter, already a devDependency, and takes the first paragraph of the body, trimmed of Markdown links and the ​ entities that genFeed.ts strips, which is the same text the home page shows as the excerpt. The home page and any page without a title get og:title from the site title and og:description from the config's description, so every page has a complete set. The existing twitter:image stays as the one image until the site has per-post images, and og:image points at the same file so cards on both networks match.
The origin is written once as a constant beside the hook and shared with genFeed.ts, which hardcodes https://blog.vuejs.org today, so the two cannot drift. The agent checks .vitepress/theme/Layout.vue and Article.vue to confirm the theme renders nothing into <head> itself, which would otherwise duplicate a tag, and keeps tsconfig.json's strict happy by typing the hook with VitePress's own PageData type. Nothing changes in the theme or the posts.
To check it, the agent runs pnpm install --frozen-lockfile and pnpm build in its sandbox, then greps .vitepress/dist/posts/vue-3-5.html for the og: and article: metas and confirms each value against the post's front matter, greps index.html for the site-wide fallback, counts that every built page has exactly one og:title, and fetches one page from pnpm preview to confirm the tags are in the served HTML rather than injected by the client. Since the site deploys from Vercel's build of the same command, no workflow or hosting change is needed.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Open Graph and Twitter card meta tags to this VitePress blog. Read .vitepress/config.ts, .vitepress/genFeed.ts, .vitepress/theme/Layout.vue, .vitepress/theme/Article.vue, vercel.json and a few files in posts/ first. Add a transformPageData hook to the config that pushes og:type, og:title, og:url, og:description, article:published_time, article:author and twitter:creator onto each post's frontmatter.head from its front matter and first paragraph, with the site title and description as the fallback for every other page, and og:image matching the existing twitter:image. Build the absolute URL the same way the feed does, with clean URLs, and share one origin constant with genFeed.ts. Change nothing in the theme or the posts. Run pnpm install --frozen-lockfile and pnpm build, grep the built HTML of one post and of the home page for the tags, check every page has exactly one og:title, and open a pull request with the 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
The pull request changes .vitepress/config.ts and the origin line of .vitepress/genFeed.ts. Its description pastes the <head> of one built post with the new metas, the home page's fallback set, and the grep count showing one og:title on every built page.
There is no workflow to run, so the evidence is the run's record: the pnpm build output, the grep over .vitepress/dist/, and the pnpm preview response for one post. A reviewer can paste the branch's Vercel preview URL into a card validator and see the same values.
Before merging, a reviewer decides whether twitter:card should move from summary to summary_large_image once per-post images exist, whether the description should come from a new description front-matter field instead of the first paragraph, and whether article:author should be a profile URL rather than a name. The posts, the theme and the feed are unchanged.
Run it on every VitePress site with bare share cards
A team with several VitePress sites sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources 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 config.ts and theme: a docs site whose pages have description in their front matter gets the description from there, and a site whose custom theme already writes <head> tags gets the hook made to skip the ones the theme owns.
After the hook is in place, no further run is needed when posts are added, since each build fills the tags from front matter. A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a site whose build broke on the change, for instance one with a post that has no title.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The tags are a short hook, but the values are only right when they follow the site's own rules: its clean URLs, its feed's origin, the entities it strips from excerpts, and whether its theme already writes into <head>. The agent reads all of that in its own sandbox, builds the site, and greps the output instead of asserting it.
The built HTML and the grep counts stay with the run and are pasted into the pull request, so the review is reading evidence rather than re-running the build. Several sites can get the same change at once, each in its own sandbox, while the person who asked keeps writing.
Frequently asked questions
Where does the description come from when a post has none?
From the first paragraph of the post, read at build time with gray-matter and trimmed of Markdown links and the entities the feed already strips. That is the same text the home page shows under each title, so cards and the index agree. If you add a description field to a post later, the hook prefers it.
Does it add per-post images?
Not on its own. The blog has one image for every card, the Vue logo named in the existing twitter:image, and the agent points og:image at the same file so both networks match. Generating a card image per post is a separate job; the pull request names the two lines to change when you have one.
Will the tags be there for crawlers, or only after JavaScript runs?
They are in the static HTML. transformPageData runs during vitepress build, so the tags are written into each .html file in the output directory, which is what the agent greps and what a crawler fetches.
Why change genFeed.ts at all?
Only to share one origin constant. The feed hardcodes https://blog.vuejs.org today, and og:url needs the same origin; keeping it in one place means a future domain change touches one line and the feed and the cards cannot disagree.