What the agent does
The agent starts by getting the site to run under its test settings, because an N+1 only shows when a listing has several items. In a Wagtail site like wagtail/bakerydemo, requirements/base.txt asks for Django>=6.0,<6.1 and wagtail>=8.0,<8.1, with django-debug-toolbar installed but commented out of INSTALLED_APPS and the middleware in bakerydemo/settings/base.py, and runtime.txt pins Python 3.12.1. The database is SQLite unless DATABASE_URL is set, through dj_database_url. bakerydemo/settings/test.py switches the cache to LocMemCache, runs background tasks with the immediate backend, and uses the MD5 password hasher. .github/workflows/ci.yml installs with uv pip install -r requirements/development.txt and runs ./manage.py check, ./manage.py makemigrations --check --noinput and ./manage.py test with DJANGO_SETTINGS_MODULE=bakerydemo.settings.test, and AGENTS.md asks for render tests under bakerydemo/<app>/tests/ with focused page setup rather than the full bakerydemo.json fixture.
Then it reads where the queries come from. BlogIndexPage.get_context in bakerydemo/blog/models.py sets posts to BlogPage.objects.descendant_of(self).live().order_by("-date_published"), and the card in templates/includes/card/blog-listing-card.html reads blog.image, a foreign key to wagtailimages.Image, renders it with {% picture blog.image format-{avif,webp,jpeg} fill-322x247-c100 loading="lazy" %}, which looks up a rendition per format, and loops blog.authors, a method that runs self.blog_person_relationship.filter(person__live=True).select_related("person") for every post. Worse, blog_index_page.html calls page.get_child_tags twice, once in {% if %} and once in the {% for %}, and that method loops every post calling get_tags, which runs self.tags.all() and self.get_parent().url per post. The bread listing has the same shape: BreadsIndexPage.paginate pages get_breads() twelve at a time, and templates/includes/card/listing-card.html reads page.image, page.origin (a foreign key to Country) and page.bread_type (a foreign key to BreadType) for each bread. The home page's featured_section_1.specific.children is get_children().specific().live(), which Wagtail already batches by content type, so that part is fine until each child card repeats the per-row foreign keys.
The measurement is a test, not a browser. Following bakerydemo/base/tests/test_home_page.py, the agent writes a WagtailPageTestCase that takes Page.get_first_root_node(), creates a Site on testserver, adds a BlogIndexPage with add_child and publishes it with save_revision().publish(), then adds several BlogPage children each with an image, two live Person authors through BlogPersonRelationship and a few tags. It clears the cache, because the list is wrapped in a wagtailcache block in the template, wraps self.client.get(index.url) in CaptureQueriesContext, and compares the count with three posts and with six: a count that grows with the rows is the N+1. The fixes go at the queryset and the method: select_related("image") on posts, prefetch_related of blog_person_relationship__person with a Prefetch whose queryset already filters person__live=True so authors() reads the prefetched rows instead of filtering again, prefetch_related("tags") for the tag loop, Wagtail's prefetch_renditions for the one filter the card uses, the parent URL computed once in get_child_tags instead of once per post, and a {% with %} in the template so get_child_tags runs once. The breads queryset gets select_related("image", "origin", "bread_type").
Each fix lands with a test that pins the count: an assertNumQueries around the index request with six posts, in a new bakerydemo/blog/tests/test_blog_index.py and a matching file for breads, so the test fails if a template change brings the N+1 back. Then the agent runs what CI runs: env DJANGO_SETTINGS_MODULE=bakerydemo.settings.test ./manage.py test, ./manage.py makemigrations --check --noinput (no model field changes, so no migration), and make lint-server, which is ruff format --check, ruff check, curlylint --parse-only bakerydemo and djhtml --check over the templates it edited, with ruff.toml at line length 88 and target-version py312. It changes no fixture data and keeps the change to the two apps, as AGENTS.md asks, and the pull request explains why each query went away and how to test it.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Find and fix the N+1 queries on this Wagtail site's listing pages. Read bakerydemo/settings/base.py and settings/test.py, AGENTS.md, bakerydemo/blog/models.py, bakerydemo/breads/models.py, bakerydemo/base/models.py, the templates under bakerydemo/templates/blog, breads, base and includes/card, and bakerydemo/base/tests/test_home_page.py first. Using DJANGO_SETTINGS_MODULE=bakerydemo.settings.test, write WagtailPageTestCase tests that build a BlogIndexPage with several published BlogPage children that each have an image, two live authors and tags, and a BreadsIndexPage with several BreadPage children that each have an image, origin and bread type, clear the cache, and count the queries of a GET to each index and to the home page with CaptureQueriesContext at two different row counts. For every count that grows with the rows, fix it at the queryset or the method with select_related, prefetch_related, Prefetch with a filtered queryset, prefetch_renditions, or a value computed once, and use {% with %} in a template where a method is called twice. Pin each fixed page with assertNumQueries at the larger row count in bakerydemo/<app>/tests/. Run ./manage.py test with the test settings, ./manage.py makemigrations --check --noinput and make lint-server. Do not change fixtures, do not add django-debug-toolbar to INSTALLED_APPS, and do not change model fields. Open a pull request with a table of each page's query count before and after at both row counts, why each query went away, and how to test it.",
"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 with three kinds of change: querysets in blog/models.py and breads/models.py that now select_related and prefetch_related what their cards read, methods such as authors and get_child_tags changed to use prefetched rows and a parent URL computed once, and two templates edited so a method is called once. Beside them are new test files under bakerydemo/blog/tests/ and bakerydemo/breads/tests/ with the page setup and an assertNumQueries per page. The body has a table of each page's query count before and after at both row counts, with a sentence per page on which relation caused the growth.
The session read at GET /o/{org}/sessions/{id} names the branch and the pull request URL, and the transcript at GET /o/{org}/sessions/{id}/messages keeps the test runs with the captured query counts, the lint output and the makemigrations --check result. GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file.
Before merging, a reviewer checks that the Prefetch for authors still excludes unpublished people, that prefetch_renditions names the exact filter the card renders, that the counts in the table do not grow between the two row counts, and runs the test suite on Postgres if production uses it, since the counts are the same but the query plans are not.
Run it on every slow-page alert
Add an automation to the Project with this prompt and a webhook trigger; Rush shows its URL and secret once. A Grafana contact point can send a custom Authorization: Bearer <secret> header, so an alert rule on the p95 latency of the blog or bread index can POST straight to the trigger, and the alert body, up to 64 KB, reaches the agent after the prompt as text, never as instructions. The automation's max_runs_per_hour, between 1 and 30, keeps a flapping alert from starting a run every evaluation.
A monitoring service that cannot add a header, or a deploy pipeline, instead calls a handler on your server that forwards the payload to the trigger URL with the secret and an Idempotency-Key made from the alert id, which dedups a retried delivery. Or it sends POST /o/{org}/sessions with this body and a request_id that is a UUID v5 of the alert id. Give that key a webhook_url and Rush POSTs run.completed when the pull request is open.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
An N+1 in a Wagtail listing hides behind three layers: the page model's queryset, the card template's foreign-key reads and image renditions, and a fragment cache that makes the page look fast after the first hit. Finding it means building pages with real relations under the test settings, clearing the cache, and counting queries at two row counts, which is a setup few people keep on a laptop. The agent builds it in its own sandbox, with uv and the requirements CI installs.
The result is a pull request whose claims are tests: an assertNumQueries per page that fails if the N+1 returns, a table of counts the transcript backs up, and the lint and migration checks CI will run again. Several sites, or several apps of one site, can be measured at once in separate sandboxes, and the sandbox parks with its virtualenv when the turn ends, so asking for the locations listing or the home page's featured sections too is a follow-up on the same session.
Frequently asked questions
Will it turn on django-debug-toolbar?
No. It is installed by requirements/base.txt but commented out of INSTALLED_APPS and the middleware, and the prompt leaves that alone. The counts come from CaptureQueriesContext inside tests under the test settings, which is also how the fix is pinned, so nothing changes in what the site serves.
The blog list is inside a wagtailcache block. Isn't that already the fix?
It hides the cost after the first request per cache key and until the fragment expires, and the tag archive and the first request after a publish still pay the full query count. The test clears the cache before counting so the measurement is of the queries, not of the cache, and the queryset fix makes the cold render cheap as well.
Won't assertNumQueries break when we add a field to the card?
Only if the field adds a query, which is what the test is for. A new foreign key read in the card fails the test by one or more queries per row, and the fix is one more entry in select_related or prefetch_related in the same pull request, so the count stays flat as the rows grow.
Does it change the demo fixture or the models?
No. AGENTS.md asks for focused page setup in tests rather than fixture changes, and the fixes are in querysets, methods and templates, so ./manage.py makemigrations --check passes with no new migration and bakerydemo/base/fixtures/bakerydemo.json is untouched.
Does it work on Postgres as well as SQLite?
The query counts are the same on both, since they come from the ORM, and the tests run on whatever DATABASE_URL names. The sandbox uses SQLite as the settings default; set DATABASE_URL as a Project secret to run the same tests against Postgres in the sandbox.
More Wagtail jobs
The same job on other stacks
- Fix N+1 Queries in a Django App (Django)
- Fix N+1 Queries in a Flask App (Flask)
- Fix N+1 Queries in a Gin API (Gin)