What the agent does
The agent reads the site as it is. In a blog shaped like gatsbyjs/gatsby-starter-blog it opens package.json and finds Gatsby 5.14 with gatsby-plugin-manifest, gatsby-plugin-feed, gatsby-plugin-image, the sharp transformers and gatsby-transformer-remark, React 18, and a test script that only prints a reminder to write tests. It reads gatsby-config.js, where gatsby-plugin-manifest is already configured with a name, a short_name of Gatsby, start_url of /, a white background_color, display: minimal-ui and src/images/gatsby-icon.png as the icon, but the theme_color line is commented out and there is no gatsby-plugin-offline entry. It reads gatsby-browser.js, which imports the two font packages, the normalize and site stylesheets and the Prism theme, and src/components/seo.js, which writes the title, description and Open Graph tags into the head.
A manifest alone does not make an installable app; browsers also want a service worker that answers when the network does not. So the agent adds gatsby-plugin-offline as a dependency and lists it in gatsby-config.js directly after gatsby-plugin-manifest, which is the order the plugin's own documentation requires so the manifest is included in the precache. It uncomments theme_color and sets it to the site's heading colour, read from src/style.css, and leaves display, start_url and the icon as they are, because they already describe the blog. Nothing in src/pages or src/templates changes.
Two details follow from reading the config. The RSS feed at /rss.xml from gatsby-plugin-feed is a generated file, not a page, so the agent excludes it from the service worker's navigation handling by passing an appendScript or a workboxConfig entry that leaves rss.xml to the network. And because gatsby-plugin-offline registers a service worker in production builds only, the agent adds a short note in README.md on how to see it: gatsby build then gatsby serve, since gatsby develop never registers one.
Proof is the build. The agent runs npm install, then npm run build, and reads public/manifest.webmanifest, public/sw.js and the icon set under public/icons that the manifest plugin generates. It runs npm run serve, opens the site in the sandbox's browser, and checks that the service worker registers and the manifest is reachable at its URL, then runs npm run format so the diff matches the repository's Prettier config. Then it opens a pull request listing the generated files a reviewer can look for.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add PWA support to this Gatsby blog. Keep the existing gatsby-plugin-manifest configuration, set theme_color, and add gatsby-plugin-offline immediately after the manifest plugin in gatsby-config.js. Leave rss.xml to the network in the service worker config. Add a short README note on testing the service worker with gatsby build and gatsby serve. Run npm run build, confirm public/manifest.webmanifest and public/sw.js exist, run npm run format, and open a pull request.",
"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. The diff adds gatsby-plugin-offline to package.json and the lockfile, adds its entry to the plugin list in gatsby-config.js with the theme_color line restored, and adds a few lines to README.md. No React component changes, because the manifest plugin already injects the <link rel="manifest"> tag and the offline plugin registers its worker from gatsby-browser hooks it provides itself. The description names the build artifacts a reviewer can check after their own gatsby build: the manifest, sw.js and the icon set.
The proof is in the trajectory at GET /o/{org}/sessions/{id}/messages: the npm run build with Gatsby's full output, the directory listing of public/ that shows the generated files, and the npm run serve session where the sandbox's browser loads the site and registers the worker. The repository has no CI workflow of its own, so the sandbox build is the check until the pull request is merged and deployed.
Before merging, a reviewer checks three things: that the offline plugin is listed after the manifest plugin and not before; that theme_color matches the site's actual heading colour rather than the commented-out example value; and that the first deploy after merging is followed by a hard reload, because a service worker that was never there before starts caching only on the second visit. Nothing is deployed by the run.
Run it on every new Gatsby site
A team that publishes several Gatsby sites from one organisation starts one run per repository with POST /o/{org}/sessions, this prompt and that repository in resources. Each run reads its own gatsby-config.js, so a site that already has gatsby-plugin-offline gets only the manifest fixes, a site with no manifest plugin gets both, and each opens its own pull request. Send a request_id per run so a retry returns the run already started.
Set a webhook_url on the API key and every run the key starts posts run.completed or run.failed when it finishes, with a session_url for the result, so a script can collect the pull request links. The key runs at most max_concurrent sessions at once, 4 by default; a Gatsby site sent beyond that is queued, answered 202 with status: "queued", and built when one of the key's slots frees.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The change is two plugin lines, and the only way to know it worked is a full production build, because gatsby develop never registers a service worker. A Gatsby build with sharp image processing is the kind of thing that ties up a laptop and a node_modules folder for a while. On Rush the run has its own sandbox with a computer and a browser in it: the agent builds, serves, loads the site and reads the registered worker, as many times as it needs, while your checkout stays on whatever you were doing.
The result is checkable rather than claimed. The diff is small enough to read in a minute, the trajectory keeps the build output and the browser session, and the description lists the artifacts in public/ so a reviewer can rebuild and compare. Several sites mean several sandboxes and several pull requests at once.
Frequently asked questions
Why is the plugin order important?
gatsby-plugin-offline precaches what earlier plugins have already produced, so it must come after gatsby-plugin-manifest for the manifest and icons to be in the cache. The agent places it directly after the manifest entry in gatsby-config.js and says so in the pull request.
Will the RSS feed still update?
Yes. gatsby-plugin-feed writes rss.xml at build time, and the service worker is configured to let that path go to the network rather than serve a cached copy, so feed readers always get the current file. The configuration line is in the diff.
How do I test it locally after merging?
Run gatsby build and then gatsby serve, open the site, and look in the browser's application panel for the registered worker and the manifest. The agent adds exactly that to README.md, because gatsby develop skips service worker registration by design.
Does this change how posts are rendered?
No. src/templates/blog-post.js, the pages and the SEO component are untouched. The manifest plugin was already injecting its link tag, and the offline plugin works from its own browser hooks, so the page markup the blog produces is the same apart from the worker registration script Gatsby adds.
Can I remove the service worker later?
Yes. Gatsby documents gatsby-plugin-remove-serviceworker for exactly that, since a worker that was once installed keeps running until something unregisters it. The pull request description mentions it so the decision is reversible.
More Gatsby jobs
The same job on other stacks
- Add PWA Support to a Nuxt App (Nuxt)
- Add PWA Support to a React Router v7 App (React Router)
- Add PWA Support to a SolidJS App (SolidJS)