What the agent does
The agent takes stock of how htmx is loaded and which of its features the pages use. In an app like bigskysoftware/contact-app, a Flask application, templates/layout.html loads a vendored static/js/htmx-1.8.0.js with a plain script tag, next to hyperscript and Alpine, and sets hx-boost="true" on the body. The templates use hx-get, hx-post and hx-delete, targets such as closest tr and next .error, triggers such as keyup delay:200ms changed, revealed and load delay:500ms, plus hx-push-url, hx-indicator, hx-confirm and hx-swap="outerHTML swap:1s". One Alpine handler in index.html calls htmx.ajax('DELETE', …) directly. There is no hx-on, no hx-sse or hx-ws and no extension, which removes several items from the migration guide before any work starts.
It then reads the guide and the new file's defaults against that list. The entry that matters here is DELETE. In htmx 2 the default methodsThatUseUrlParams is ['get', 'delete'], so a DELETE request carries its parameters in the URL and not in a form-encoded body. In app.py, contacts_delete_all reads the ticked checkboxes with request.form.getlist("selected_contact_ids"). After the swap that list would be empty, the loop would delete nothing, and the handler would still flash its success message and render the page. No error appears anywhere. The single-row delete puts the id in the path and the archive reset sends no parameters, so those two keep working, and that contrast is why this break is easy to miss.
The agent fixes it on the server and names the alternative. It changes the handler to read the ids from the query string, and notes that setting htmx.config.methodsThatUseUrlParams to ["get"] restores the old body without touching Python, at the cost of keeping non-standard behaviour. It checks the other changed default, selfRequestsOnly, against the templates and finds only relative URLs. It takes dist/htmx.js for the current 2.x release from the htmx.org package on npm, saves it under the versioned file name the app already uses, removes the 1.8.0 file, updates the script tag and records the new file's checksum.
The proof is a browser, before and after. The agent installs the pinned requirements.txt, starts the app and drives each interaction on htmx 1 first: search as you type, the lazy contact count, inline email validation on the edit page, the archive progress polling and download, deleting one row through its confirm dialog, and ticking several rows for bulk delete. It records the requests each one sends. Then it repeats the list on htmx 2. Because Contact.save_db rewrites contacts.json on every change, it restores that file from git between passes so both start from the same seventeen contacts and no data change reaches the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade this app from htmx 1 to the current htmx 2 release. Read the layout template for how htmx is loaded, every template for the hx- attributes and any direct htmx JavaScript calls, and the server routes those attributes call. Read the official htmx 1 to 2 migration guide and the config defaults in the new htmx.js, and make a table of each change with whether this app is affected and where: DELETE parameters moving to the URL, selfRequestsOnly, scrollBehavior, hx-on syntax, hx-sse and hx-ws, extensions, and module paths. For every hx-delete or htmx.ajax DELETE that sends parameters, find the server handler and make it read them from the query string; describe the methodsThatUseUrlParams config alternative without using it. Get dist/htmx.js for the new version from the htmx.org npm package, store it the way the app stores the old file, update the script tag, delete the old file and report the new file's SHA-256. Do not change other libraries. Before the swap and again after it, install the pinned requirements, start the app, and in a real browser exercise every htmx interaction: active search, lazy-loaded content, inline validation, polling, single delete with its confirm dialog, and bulk delete of several selected rows. Record the method, URL and body of each request and whether the page ended in the expected state. Restore any data file the app rewrites between passes and keep it out of the diff. Report anything broken on both versions separately. Open a pull request with the table, both passes and the request log.",
"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
The pull request contains the new vendored file, the deletion of the old one, a one-line change to templates/layout.html and the handler change in app.py. Its description leads with the migration table: each item from the guide, whether the app uses the feature, and the file and line when it does. Below that are the two browser passes side by side, one row per interaction, with the request each sent. The bulk delete row is the one to read: on htmx 1 the ids travel in the body, on htmx 2 in the query string, and the count of contacts afterwards shows whether the handler found them.
Problems that exist on both versions are listed apart from the upgrade. In this app that would include the spinner image the templates request from /static/img/, a directory the repository does not contain, and the bulk delete button addressing /contacts while the route is declared as /contacts/; the agent reports what the browser and Flask did with each and changes neither. A reviewer checks the checksum against the npm package, confirms the handler reads from the query string, and repeats the bulk delete by hand, since a silent no-op is a failure no test or error log would report.
Run it on every first of the month
Once the app is on htmx 2, later releases are small, and a schedule keeps a vendored file from drifting. Create an automation in the Project that holds the repository with a schedule trigger whose cron is 0 9 1 * * and a prompt that says: read the version string in the vendored htmx file and the latest htmx.org version on npm; if npm is newer within the same major, replace the file, repeat the browser checks from this page and open a pull request; if not, end with one line. Only a run that finds a newer release opens anything.
An agency with the same library vendored into many client sites sends this page's body once per repository from its own server, each call a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name and the target htmx version. A repeated call returns the run already started, and each run builds its own table from that site's templates.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This upgrade fails quietly. The page loads, the button responds, the flash message says the contacts were deleted, and they are still there. A test suite that only checks status codes passes, and a reviewer reading a one-line script tag change has nothing to object to. Finding it takes someone to click every interaction and look at what was sent, and the agent has a browser in its sandbox for that. Each request and each resulting page state is kept in the run's record, so the pull request shows the break and the fix as observed.
It also reads the server and the templates together, which is where a hypermedia app keeps its contract. An attribute in one file and a request.form in another are a pair, and the migration guide only describes one half. The agent matches every hx-delete to its route before deciding anything. Ten small sites on the same library are ten runs, each matching its own pairs.
Frequently asked questions
What actually breaks when moving from htmx 1 to htmx 2?
For most apps the main one is DELETE: parameters move from a form-encoded body to the URL, so a handler that reads the body sees nothing. Cross-origin requests are refused by default, hx-on attributes need the hx-on: form, extensions ship separately, and hx-sse and hx-ws become extensions. The agent checks each against your templates and reports which apply.
Can I keep the old DELETE behaviour instead of changing my server?
Yes. Setting htmx.config.methodsThatUseUrlParams to ["get"] makes DELETE send a body again. The agent fixes the handler by default so the app runs on htmx 2's own defaults, and it describes the config route in the pull request so you can choose.
We load htmx from a CDN, not a vendored file. Does that change the job?
Only the swap itself. The agent updates the script tag's version and, where the tag has an integrity attribute, computes the new hash from the file it downloaded. The table, the handler fixes and the browser passes are the same.
Does it upgrade hyperscript or Alpine at the same time?
No. The prompt limits the change to htmx so that any difference between the two browser passes has one possible cause. If those libraries are also behind, ask for them in a separate run.
More htmx jobs
More jobs like this: Upgrade dependencies weekly
- Upgrade Husky 7 to 9 Without Breaking Installs or Git Hooks (Husky)
- Upgrade a Quarkus App to Java 25 (Quarkus)
- Upgrade a Spring Boot App to Java 25 (Spring Boot)