What the agent does
A Cypress version is written in more places than package.json, and a major upgrade that misses one of them passes locally and fails in CI. So the agent lists them first. In a project like cypress-io/cypress-example-kitchensink, package.json pins cypress at exactly 16.2.1 and eslint-plugin-cypress at 7.0.2, lists cypress under allowScripts, and sets engines.node to ^22.22.2 || ^24.15.0 || >=26.0.0. .npmrc has save-exact=true and a min-release-age of 7 with cypress excluded from it. Six GitHub workflows run the suite: four of them through cypress-io/github-action pinned by commit, and four inside the cypress/browsers:24.22.1 container image, whose tag fixes the browser versions the recorded jobs use. .node-version names the Node that CI installs.
It then reads why the upgrade has not already happened. renovate.json automerges updates, with two exceptions that matter here: major updates have automerge off, and the cypress/base and cypress/browsers images are grouped and capped by allowedVersions. A new Cypress major therefore sits as an open pull request until a person takes it. The agent takes it. It reads the changelog and the migration guide for each major between the pinned version and the target, and turns them into a checklist: commands and config keys that were removed or renamed, the Node versions the new major supports, the browser versions it supports, and the plugin majors that match.
The specs are the test of the upgrade. After npm install --save-exact cypress@<target> and npx cypress verify, the agent installs Chrome and Firefox in its sandbox and runs the three scripts the repository already has for this: npm run test:ci, test:ci:chrome and test:ci:firefox, each of which starts the static server with run-p --race and runs all twenty spec files. No record key exists in the sandbox, so it uses these non-recording scripts and not the :record ones. A spec that fails only on the new major points at a line in the checklist; the agent applies the documented replacement in the spec and, where a helper is shared, in cypress/support/commands.js. In a suite that also documents the commands, as this one does under app/commands/*.html, the page that shows the old usage changes in the same commit.
Then the surrounding pins move as far as the checklist allows. If the new major drops a Node line, engines.node and .node-version follow. The container tag moves to an image whose browsers the new major supports, within the cap renovate.json sets. eslint-plugin-cypress moves if the new major needs a newer plugin, and npm run lint must pass afterwards, since here npm run build is an alias for the lint and it covers the workflow YAML as well as the JavaScript. The action pin is left alone unless the migration guide names a minimum version. The lockfile is whatever npm install wrote; the agent does not edit package-lock.json by hand.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade Cypress in this repository to the current major version. Read package.json, .npmrc, .node-version, cypress.config.js, cypress/support, renovate.json, every workflow under .github/workflows and AGENTS.md if present, and list every place a Cypress version, a cypress/ Docker image tag or a supported Node version is written. Read the Cypress changelog and migration guide for each major between the pinned version and the target and write a checklist of removed or renamed commands and config keys, supported Node versions, supported browsers and matching plugin versions. Install the target with npm install --save-exact, run npx cypress verify, install Chrome and Firefox, and run npm run test:ci, npm run test:ci:chrome and npm run test:ci:firefox; do not use the record scripts. Fix each spec that fails with the replacement the migration guide documents, and update any page under app/ that documents the old usage. Move engines.node, .node-version, the Docker image tags and eslint-plugin-cypress only as far as the new major requires, staying within the limits renovate.json sets. Run npm run lint. Do not add retries, skip tests, add a yarn.lock or change the npm scripts' names. Open a pull request with the checklist, each item marked applied or not applicable with the file it touched, and the summary lines of the three browser runs.",
"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 package.json and package-lock.json, the specs and support files the new major required, any documentation page that showed a removed usage, and whichever of .node-version, engines.node and the workflow image tags had to follow. The description carries the migration checklist with every item marked applied, with the file it touched, or not applicable, with the search that found no use of it.
Under the checklist are the summary tables Cypress prints at the end of each run, for Electron, Chrome and Firefox, from the agent's sandbox. They are not a substitute for the repository's own CI, which runs on the pull request with the pinned container image and, for recorded jobs, the project's record key. They show the reviewer that the spec changes were made against a passing run and not from reading alone.
A reviewer checks that no spec lost an assertion in the rewrite, and reads any change to .node-version with care: in a repository that other pipelines clone and run, as this one's AGENTS.md describes, that file is read by someone else's CI as well.
Run it on every new Cypress major release
Renovate already opens a pull request when a major lands, and with major automerge off it waits. A label on that pull request starts nothing: a github trigger fires only for a pull request an owner, member or collaborator wrote, and Renovate's was written by a bot. So a maintainer opens an issue that names the target major, and an automation in the Project with this prompt and a github trigger on issues.labeled, with the label the team uses for upgrades they want worked in labels, starts one run when that label is applied. The trigger puts the issue after the prompt, so the agent reads the target version from it.
Across many repositories, a script on your server lists them with GET /o/{org}/github and sends this body once per repository to POST /o/{org}/sessions, each with a request_id that is a UUID v5 of the repository name and the target major, so a rerun of the script starts nothing twice. A key runs a limited number at once and queues the rest, oldest first.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The work is mostly waiting on browsers. Three full runs of the suite, repeated after each batch of fixes, with Chrome and Firefox installed beside the Cypress binary, is the kind of job that takes over a laptop for an afternoon. In a Rush sandbox it runs unattended, and the commands and their output, failed attempts included, are kept in the run's transcript.
It is also work where the proof matters more than the diff. A version bump is one line; whether the suite still passes in every browser the team supports is the question. The pull request arrives with that answer attached, and the session read at GET /o/{org}/sessions/{id} names the pull request and what the run cost.
Frequently asked questions
Why not let Renovate do it?
Renovate changes the version and stops there. A major release that removes a command leaves the specs failing, and the bot's pull request stays red until someone rewrites them. The agent starts from the same bump and does the rewriting, with the browser runs to show it worked.
Does it upgrade across several majors at once?
It reads the migration guide for every major in between and applies them in order, running the suite after each step so a failure is tied to one guide. If one step cannot be completed, the pull request stops at the last major that passes and lists what blocked the next.
Can the sandbox record to Cypress Cloud?
Not without a record key, and the prompt tells the agent to use the non-recording scripts. Recording, parallel groups and the commit statuses they produce belong to your CI, which runs them on the pull request with its own secrets.
What about the Docker image tags?
The agent moves them only when the new Cypress major needs browsers or a Node line the current image lacks, and it stays within the cap set in renovate.json. The tag change is in the same pull request so the recorded jobs and the binary change together.
More Cypress jobs
More jobs like this: Upgrade dependencies weekly
- Upgrade dbt and Its Packages (dbt)
- Upgrade ASP.NET Core Dependencies Every Week (ASP.NET Core)
- Upgrade Astro Dependencies Every Week (Astro)