What the agent does
The agent reads how dark styles reach the page today before it adds a button, because a custom VitePress theme can follow the system, a class, or both. In a blog like vuejs/blog, package.json has vitepress ^1.3.4, vue ^3.5.0-beta.3, tailwindcss ^3.4.10, @tailwindcss/typography, feed and gray-matter, with pnpm@9.8.0 as the package manager and dev, build, serve and preview scripts. .vitepress/config.ts sets cleanUrls: true, Twitter and icon head entries, a Fathom analytics script and buildEnd: genFeed, and says nothing about appearance, so VitePress's default of true applies. .vitepress/theme/index.ts exports only a Layout, with no default theme imported, and postcss.config.js configures Tailwind inline with content: ['./.vitepress/theme/**/*.vue'] and the typography plugin, and no darkMode setting, so Tailwind's dark: variants follow prefers-color-scheme. The components already carry those variants everywhere: Layout.vue wraps the page in antialiased dark:bg-slate-900 and gives the nav links dark:text-white and dark:hover:text-gray-200; Home.vue and Article.vue use dark:text-white, dark:divide-slate-200/5, dark:text-gray-300 and prose dark:prose-invert; and style.css has one @media (prefers-color-scheme: dark) block for inline code colours plus a .vp-code span { color: var(--shiki-dark, inherit) } rule for code blocks. So the blog is dark when the operating system is, and a reader cannot choose.
VitePress already ships the part people usually write by hand. With appearance left on, it injects an inline script before render that reads the vitepress-theme-appearance key from local storage and puts a .dark class on <html>, so there is no flash on load, and useData() hands a theme isDark, a Ref<boolean>, that tracks that class. The agent therefore changes Tailwind rather than the components: darkMode: 'class' in the inline Tailwind config in postcss.config.js, which makes every existing dark: variant key off the .dark class VitePress manages instead of the media query, so none of the dark: utilities in the three components move. The one @media (prefers-color-scheme: dark) block in style.css becomes a .dark selector so inline code follows the toggle too, and the Shiki rule needs no change because VitePress sets --shiki-dark under the same class.
The toggle itself is a small component. The agent writes .vitepress/theme/AppearanceToggle.vue, a <button> with an aria-label that reads isDark from useData() and flips it on click, and places it in Layout.vue's nav after the RSS link with the same text-sm and separator dot the other links use, so the header's rhythm holds. Writing to isDark is what VitePress's own default theme does for its switch, and the write updates the .dark class and the local storage key through the appearance handling, so the choice survives a reload and the next page. Because Layout.vue is the only layout and NotFound.vue renders inside it, the 404 page gets the toggle for free. The vp-raw class on the RSS link is left as it is.
Then it builds and looks. In its own sandbox the agent runs pnpm install and pnpm build, which also runs genFeed into .vitepress/dist/feed.rss, then pnpm preview and opens the home page and a post such as posts/vue-3-5.md in its browser: it emulates a dark system scheme and confirms the page is light until the toggle is pressed and dark after, reloads to confirm the choice persists through the inline script with no flash, and screenshots both states on both pages. It also checks the prose dark:prose-invert article body and an inline code span in each state, since those are where the Tailwind and CSS changes meet, and runs a build-size comparison of the main CSS asset before and after to show the class strategy added nothing measurable.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a dark mode toggle to this VitePress blog, which has a custom Tailwind theme and no default theme. Read package.json, .vitepress/config.ts, .vitepress/theme/index.ts, Layout.vue, Home.vue, Article.vue, NotFound.vue, style.css and postcss.config.js first, and list every place dark styles come from today. Keep VitePress's appearance setting on and use its inline script and the isDark ref from useData rather than writing your own storage code. Switch Tailwind to the class dark mode strategy so the existing dark variants follow the html class, and rewrite the one prefers-color-scheme block in style.css to the same class. Add a small toggle component to the nav in Layout.vue in the style of the existing links. Run pnpm install and pnpm build, serve the build, open the home page and one post in the browser with a dark system scheme, confirm the toggle and that the choice persists across a reload, screenshot light and dark on both pages, compare the main CSS asset size before and after, and open a pull request with the screenshots and the measurements.",
"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
A pull request that changes postcss.config.js, .vitepress/theme/style.css and Layout.vue, adds AppearanceToggle.vue, and touches no post. The description lists where dark styles came from before, shows the toggle in the nav, and carries four screenshots from the sandbox browser, light and dark on the home page and on a post, plus the CSS asset sizes before and after and a note that reload kept the choice.
The repository deploys through Vercel with vercel.json, so the pull request gets a preview deployment from that integration rather than a GitHub workflow, and a reviewer opens it to try the toggle. They decide whether the default for a first visit should follow the system, which the pull request keeps, or start light, which is one appearance value in config.ts.
Run it on every reader request for a theme switch
A team that runs several VitePress sites with custom themes starts one run per repository from its own server: a POST /o/{org}/sessions each, with this prompt as input, the 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 that site's theme, so a site that already uses the default theme's VPSwitchAppearance gets a note and no change, and a site on Tailwind 4 gets the @custom-variant dark line instead of a darkMode key.
The key's webhook_url receives run.completed for each run, with the session_url to read the pull request link from, and the Vercel preview on each pull request is where the team looks at the result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A dark mode toggle is a common request with a common failure: a theme that writes its own local storage code and flashes light on every load, or a Tailwind config that switches to the class strategy while one stylesheet still listens to the media query, so code spans stay light in a dark page. The agent reads the three components and the stylesheet, uses the script VitePress already injects, and checks the result in a real browser with a dark system scheme, reloads included, so the pull request shows the toggle working rather than describing it.
Every command and screenshot stays with the run, and the pull request quotes the build and the asset sizes. The same change across a team's sites costs no more attention than one, because each run reads that site's theme and opens its own pull request.
Frequently asked questions
Why not write a toggle that sets a class and saves to local storage?
VitePress already does that with its appearance option: an inline script restores the stored choice before the first paint and useData().isDark reflects it, so a hand-written version would duplicate it and risk a flash on load. The component only reads and writes isDark.
Do the existing dark: classes in the components change?
No. Switching Tailwind to darkMode: 'class' makes every existing dark: variant follow the .dark class on <html> instead of the media query, so Layout.vue, Home.vue and Article.vue keep their classes. The one @media (prefers-color-scheme: dark) block in style.css is rewritten to the same class.
What does a first-time visitor see?
The system scheme, as today, because VitePress's appearance script falls back to prefers-color-scheme when nothing is stored. Pressing the toggle stores a choice that wins from then on; a team that prefers a light default changes the appearance value in config.ts.
Does the RSS feed or the analytics script change?
No. genFeed still runs at buildEnd and writes feed.rss, and the Fathom script in head is untouched. The pull request shows the feed file in the build output to confirm the build end hook still ran.
More VitePress jobs
The same job on other stacks
- Add Dark Mode to a Vue App (Vue)
- Add Dark Mode to a Zola Theme (Zola)
- Add Dark Mode to an Angular App (Angular)