What the agent does
The agent starts with what the site is built from. In a blog like 11ty/eleventy-base-blog, package.json has "type": "module", engines.node of >=18, an .nvmrc of 22, a package-lock.json at lockfile version 3, and no test script at all: build is npx @11ty/eleventy, start adds --serve --quiet, and build-ghpages passes --pathprefix=/eleventy-base-blog/. Everything is a devDependency except @zachleat/heading-anchors: @11ty/eleventy ^3.1.7, @11ty/eleventy-img ^7.0.0, @11ty/eleventy-navigation ^1.0.5, @11ty/eleventy-plugin-rss ^3.0.0, @11ty/eleventy-plugin-syntaxhighlight ^5.0.2, cross-env ^10.1.0, luxon ^3.7.2, prismjs ^1.30.0 and zod ^4.4.3. There is a .github/dependabot.yml for npm on a monthly schedule with a seven-day cooldown and versioning-strategy: increase, but the only workflow is gh-pages.yml.sample, so nothing builds the site on a pull request today.
It then reads how each package is used, because that decides which bumps are safe to take blind and which need a look. eleventy.config.js imports IdAttributePlugin, InputPathToUrlTransformPlugin and HtmlBasePlugin from Eleventy itself, feedPlugin from the RSS plugin with type: "atom" and outputPath: "/feed/feed.xml", eleventyImageTransformPlugin with formats: ["avif", "webp", "auto"], and registers two bundles with addBundle plus a drafts preprocessor. _data/eleventyDataSchema.js calls z.object, z.optional, safeParse and z.prettifyError, an API that exists only from Zod 4. _config/filters.js uses DateTime.fromJSDate and toFormat from Luxon. And _includes/layouts/base.njk inlines node_modules/@zachleat/heading-anchors/heading-anchors.js by path inside a <script type="module">, so a release of that package that renames the file breaks the build rather than the page.
With that map, the agent runs npm ci on Node 22, then npm outdated to see what moved. Minor and patch updates inside the existing caret ranges go in first with npm update, which rewrites only package-lock.json. Each major it finds is taken on its own: it reads that package's changelog, bumps the range in package.json, installs, and rebuilds. For Eleventy and its plugins it watches the plugin options named above; for luxon it checks the two filters still format dd LLLL yyyy and yyyy-LL-dd; for zod it checks z.prettifyError is still exported; for prismjs it checks the syntax highlight plugin's peer range. A major it cannot make build is left out and named in the description with the error it produced.
The proof is the build. Before touching anything the agent runs npm run build and keeps the _site folder; after the upgrade it builds again and diffs the two trees: the list of HTML files, feed/feed.xml, sitemap.xml, and the avif and webp files the image plugin wrote for content/blog/fourthpost/possum.png. A diff that is only the currentBuildDate comment at the foot of each page is the expected result; anything else, such as a changed heading id from IdAttributePlugin or a feed entry that lost its <updated>, is reported line by line. It finishes with npm audit and npm ls to show no advisory and no unmet peer dependency.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade this Eleventy site's npm dependencies. Read package.json, package-lock.json, .nvmrc, eleventy.config.js, _config/filters.js, _data/eleventyDataSchema.js and _includes/layouts/base.njk first, and note that base.njk inlines a file from node_modules by path. Run npm ci and npm run build on the Node version in .nvmrc and keep the _site output as a baseline. Apply minor and patch updates with npm update, then take each major version separately, reading its changelog and checking the plugin options, filters and schema calls this site uses. Rebuild after each step and diff _site against the baseline, ignoring only the build date comment; report every other difference. Leave out any major that does not build and say why. Finish with npm audit and npm ls. If no workflow builds the site on pull requests, add one in a separate commit. Open a pull request whose description lists each package with its old and new version and the build diff.",
"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 that changes package.json and package-lock.json and, when a major needed it, one source file such as eleventy.config.js or _data/eleventyDataSchema.js with the smallest edit that keeps the site building. Patch and minor bumps sit in one commit; each major is its own commit with the changelog link in its message, so a reviewer can drop one without losing the rest.
The description is a table of packages with the version before and after, the npm outdated output the run started from, the _site diff summary (files added, removed or changed, with the build-date comment filtered out), the npm audit line and any major the agent left behind with the error it hit. The transcript at GET /o/{org}/sessions/{id}/messages keeps every npm and eleventy command with its full output.
Before merging, a reviewer reads the diff summary rather than the lockfile: an unchanged page set and an unchanged feed/feed.xml mean the upgrade is invisible to readers. If an image or heading id changed, the description names the file and the reviewer opens the built page to decide. Because this site has no pull-request workflow, the reviewer can also take the agent's suggested build.yml, offered as a separate commit, so the next weekly run is checked by GitHub too.
Run it on every Monday morning
Create an automation in the Project that holds the site with a schedule trigger, a cron such as 0 7 * * 1 in your timezone, and this prompt. Every Monday one run installs, upgrades, rebuilds and diffs, and opens one pull request; a week with nothing outdated opens none and says so in its result. An automation run has its own max_runs_per_hour cap.
To start it from your own scheduler instead, send POST /o/{org}/sessions with this body and the repository in resources, and include a request_id that is a UUID v5 of the repository name and the ISO week, so a retried call returns the run already started rather than opening a second pull request.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
An Eleventy site has no test suite to tell you an upgrade was safe; the only evidence is the built output, and comparing two _site trees by hand is the step nobody does. The agent does it every time, in a sandbox with the exact Node from .nvmrc, and keeps the before-and-after build logs with the pull request.
The majors are the part that costs attention: a plugin option renamed, a Zod helper moved, a file path under node_modules that a layout inlines. Reading each changelog against the files that call the package is slow on a laptop and routine for an agent, and doing it weekly keeps each pull request to a few lines instead of a quarterly rewrite. Many sites can run at once, each in its own sandbox with its own pull request.
Frequently asked questions
How does it know the upgrade did not change the site, with no tests?
It builds before and after and diffs the two _site trees: the HTML files, feed/feed.xml, sitemap.xml and the images the image plugin generates. The only expected difference is the currentBuildDate comment at the end of each page, which it filters out; everything else is listed in the pull request for a reviewer to judge.
There is already a dependabot.yml. Why run this too?
Dependabot opens one pull request per package on its monthly schedule and never builds the site, so a plugin major and the config change it needs arrive as a red pull request with no fix. The agent takes all the updates together, makes the config edit a major needs, and shows the build. Keeping dependabot.yml for security advisories alongside it is fine.
What happens with a major that breaks the build?
It tries the fix the changelog describes, such as a renamed plugin option in eleventy.config.js. If the build still fails, it reverts that one package to its previous range, keeps everything else, and names the package and the error in the description so you can decide whether to take it by hand.
Does it touch the heading-anchors script inlined in base.njk?
Only if the package's new release moves or renames heading-anchors.js, which the build would catch because the include would fail. In that case the agent updates the path in _includes/layouts/base.njk in the same commit as the bump and points to it in the description.