What the agent does
The agent reads the layouts and every script before turning on client-side navigation, because those scripts are what breaks. In withastro/blog-tutorial-demo on its complete branch, package.json has Astro ^7.0.3 with @astrojs/preact and @astrojs/rss, astro.config.mjs sets site and the Preact integration, and tsconfig.json extends astro/tsconfigs/strict with Preact's JSX source. src/layouts/BaseLayout.astro is the one layout every page uses: a head with the favicon, viewport, Astro.generator and a pageTitle prop, then Header, an h1, the slot, Footer, and a bundled <script> that imports ../scripts/menu.js. MarkdownPostLayout.astro wraps it for the four posts in src/pages/posts/*.md, printing date, description, author, image and tag links. Header.astro renders ThemeIcon, Menu and Navigation; ThemeIcon.astro carries an is:inline script that reads localStorage or prefers-color-scheme, toggles the dark class on documentElement, and binds a click handler with getElementById('themeToggle'); scripts/menu.js binds one click handler on .menu that flips aria-expanded. index.astro renders a Preact Greeting island with client:load; blog.astro, about.astro, tags/[tag].astro, tags/index.astro and rss.xml.js complete the site. Nothing imports from astro:transitions today, so each link is a full page load.
The change begins with one line: import { ClientRouter } from 'astro:transitions' and <ClientRouter /> in the head of BaseLayout.astro, which turns every internal link on every page into a client-side navigation with the browser's view transition where it is supported and a plain swap where it is not. Then the scripts. The theme script is is:inline, so after a swap the new document's <html> arrives without the dark class until something re-applies it; the agent moves the class-setting code into a function and calls it both on first load and from a document.addEventListener('astro:after-swap', ...) listener, so the new page is dark before it paints and there is no flash. The click handler for the toggle, and the .menu handler in menu.js, are bound to elements that are replaced on each navigation, so both move under astro:page-load, which fires on first load and after every navigation; the agent chooses listeners over the data-astro-rerun attribute so each script attaches exactly once per page and says why in the pull request.
Two small touches make the result visible. The post title gets a transition:name derived from the post's slug in both blog.astro's list and MarkdownPostLayout.astro's heading, so clicking a post animates its title into place, and the Header gets transition:persist so the open menu state survives moving between pages. The Preact Greeting island needs nothing, since the router hydrates islands on the new page as it would on a load. rss.xml.js is a non-HTML endpoint and is untouched.
Checking happens in a real browser, which the sandbox has. The agent runs npm run build, then npm run preview, opens the site, and navigates Home to Blog to a post to Tags, confirming on each step that no full load happened, that the dark class is still present after each swap when the theme is dark, that the menu toggle and theme toggle still respond, and that the feed at /rss.xml still serves. It also toggles the system's reduced-motion preference, under which the router skips the animations by default, and records that the pages still swap.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add view transitions to this Astro site. Read package.json, astro.config.mjs, every file under src/layouts, src/components, src/scripts and src/pages first, and list every script and where it binds to the DOM. Add the ClientRouter from astro:transitions to the base layout's head. Make the inline theme script re-apply the dark class on astro:after-swap and bind its click handler on astro:page-load, and move the menu script's handler under astro:page-load as well, so neither double-binds; explain why you chose lifecycle events over data-astro-rerun. Give post titles a transition:name shared between the blog list and the post layout, persist the header across navigations, and leave the RSS endpoint and the Preact island alone. Build the site, serve the preview, and in the browser navigate between the home, blog, a post and the tags pages checking that no full load occurs, that the dark theme survives each navigation, that both toggles still work and that the feed still serves; check once with reduced motion on. Open a pull request that lists each script you changed and what you observed in the browser.",
"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 that edits src/layouts/BaseLayout.astro, src/layouts/MarkdownPostLayout.astro, src/components/Header.astro, src/components/ThemeIcon.astro, src/scripts/menu.js and src/pages/blog.astro. Its description lists each script with the event it now listens on and why, names the shared transition on post titles, and reports what the agent saw in the browser on each navigation.
The run's record keeps the astro build output and the browser session, so a reviewer can watch the navigations and the dark class persisting without rebuilding the site themselves.
Before merging, a reviewer opens the preview on the pull request's deploy, tries the theme toggle after two or three navigations, and checks a browser without native view transitions to confirm the swap still happens with no animation, which is the fallback the router promises.
Run it on every Linear issue labelled site
A team that tracks website work in Linear adds an automation with a linear trigger on linear.issue.labeled for the label site, the Project that holds this repository, and this prompt. Labelling the issue that asks for smoother navigation starts one run; the issue's text is added after the prompt, so a request for a particular animation or for excluding a page reaches the agent as written.
The trigger fills in no placeholder, so the next site issue on the same automation, a prefetch strategy or a scroll restoration fix, only needs to say what the visitor should see.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Turning on client-side routing is one line; the work is every script that assumed a fresh document, and the only way to know which ones you missed is to click through the site after the change. The agent does that in its own sandbox with a real browser, checks the exact states that break, the theme class after a swap and handlers on replaced elements, and keeps the session in the run's record.
The pull request explains each script change against the router's lifecycle events rather than leaving a reviewer to rediscover why the theme flashed, which is the difference between a change that gets merged and one that gets reverted a week later.
Frequently asked questions
Why ClientRouter and not ViewTransitions?
ClientRouter is the component Astro exports from astro:transitions for client-side navigation with view transitions; it is the current name of the component earlier versions called ViewTransitions. On Astro 7 the agent imports ClientRouter, and the pull request notes the old name for readers following older tutorials.
Why not just add data-astro-rerun to the inline script?
data-astro-rerun makes an inline script execute again after every transition, which would re-read the theme and rebind the click handler, but it also re-runs everything else in the script each time. Listening on astro:after-swap for the class and astro:page-load for the handler attaches once and runs exactly the needed code at the right moment, which is easier to reason about as the script grows.
What happens in a browser without the View Transitions API?
The router still intercepts links, fetches the next page and swaps the document, so navigation stays client-side; only the animation is skipped. The agent checks this path and the reduced-motion path in the browser, and the pull request reports both.
Does the Preact island keep working?
Yes. The Greeting island on the home page is rendered with client:load, and the router hydrates islands on the incoming page the same way a full load does. The agent confirms the island responds after navigating away and back; transition:persist on an island is only needed when its state must survive, which this one has no need for.