What the agent does
The agent clones the repository into its own cloud sandbox and finds the queries worth caching before adding a dependency. In miguelgrinberg/microblog, app/models.py gives User three methods, followers_count, following_count and posts_count, each a SELECT count() over a subquery, and to_dict calls all three, so GET /api/users and the followers and following lists in app/api/users.py run three count queries per user per page. The profile template shows the same counts on every /user/<username> page. config.py already has REDIS_URL with redis:// as the default and POSTS_PER_PAGE 25, create_app in app/__init__.py already builds app.redis and an rq queue on it, and requirements.txt pins Flask 3.0.0, Flask-SQLAlchemy 3.1.1, SQLAlchemy 2.0.23 and redis 5.0.1, so a Redis-backed cache adds no new service.
It reads the write paths too, because a cached count is only right if every change clears it: follow and unfollow in app/main/routes.py and the User.follow and unfollow methods they call, the index route that creates a Post, and create_user in the API. tests.py is a unittest suite with a TestConfig that uses an in-memory SQLite database and turns Elasticsearch off, and test_follow already asserts following_count() and followers_count() before and after a follow, which makes it the natural place to prove invalidation.
The change adds Flask-Caching to requirements.txt, a cache = Cache() in app/__init__.py initialised in create_app, and three config keys in config.py: CACHE_TYPE from the environment with RedisCache as the default, CACHE_REDIS_URL set to REDIS_URL, and CACHE_DEFAULT_TIMEOUT. The three count methods get @cache.memoize(), keyed on the user, and follow, unfollow, post creation and user creation call cache.delete_memoized for the users they touch, in the model methods so the API and the web routes share one path. TestConfig sets CACHE_TYPE to SimpleCache, so the suite runs without Redis.
New tests extend tests.py: one that calls followers_count(), inserts a follower row directly, sees the memoized value, calls delete_memoized and sees the new one, proving the cache is live; and one that goes through follow() and sees the count change at once, proving the invalidation. The agent runs python -m unittest tests -v and, with SQLALCHEMY_ECHO on, loads /api/users twice in the sandbox to show the count queries appear once. It opens a pull request that links back to the issue and notes that the Docker image and boot.sh need no change because Redis is already required for the task queue.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labeled agent says: \"Profile pages and the users API are slow; every user shows three count queries. Cache the follower, following and post counts and make sure they stay correct when someone follows, unfollows or posts.\" Do the work in this Flask app. Read config.py, app/__init__.py, app/models.py, app/main/routes.py, app/api/users.py, requirements.txt, tests.py and the Dockerfile first. Add Flask-Caching backed by the Redis the app already configures, memoize the three count methods, invalidate them on every write path including the API, keep the test configuration free of Redis, add unittest cases that prove both the caching and the invalidation, run the suite, and open a pull request that links back to the issue.",
"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 links to the issue. The diff touches requirements.txt, config.py, app/__init__.py, app/models.py and tests.py, and nothing in the templates or the API module, because the memoized methods keep their names and the invalidation lives in the model. The description lists the three cache keys and every write path that clears them.
The run's record keeps the unittest output with the existing four tests and the new ones named, and the SQLAlchemy echo from two requests to /api/users showing the count queries on the first and not the second, so a reviewer can see the effect without a Redis of their own.
Before merging, a reviewer checks that no write path outside the model changes followers or posts, such as a CLI command or an rq task, confirms CACHE_DEFAULT_TIMEOUT is a sensible bound in case one is missed, and decides whether unread_message_count, which the base template calls on every page, should get the same treatment next.
Run it on every Linear issue labeled agent
In the console, an automation with a linear trigger on your triage label, in the Project that has the repository, starts one run per labeled issue with that issue appended to this prompt, each in its own sandbox and each ending in its own pull request. From a server, the same run is POST /o/{org}/sessions with the issue named in resources as https://linear.app/<workspace>/issue/<ID>, read through your Linear connection, beside the repository.
Give the API key a webhook URL and each run it started reports run.completed or run.failed with the session_url, so your handler can post the pull request link on the issue. A request_id in the body keeps a retried delivery from starting the same run twice.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Caching is correct only when the stale case and the invalidated case are both tested, and faster only when the query log says so. The sandbox installs the app, runs the suite and the two echoed requests, and keeps the output, so the pull request carries evidence instead of a timing estimate.
The work spans the configuration, the models, the routes and the tests, and the invalidation has to cover every path at once or the feature is a bug. One run returns a single pull request with all of it, and the same prompt runs across several Flask services in parallel, each reading its own write paths.
Frequently asked questions
Why not cache the whole page or API response?
The profile page and the API responses include per-viewer parts such as the follow button and the caller's token, and the lists are paginated. Memoizing the three count methods removes the repeated queries everywhere they are called without caching anything viewer-specific.
What backs the cache?
RedisCache on the REDIS_URL the app already uses for rq, so no new service is needed. CACHE_TYPE comes from the environment, and the test configuration sets SimpleCache so unittest runs without Redis.
How does it stay correct?
Every write that changes a count calls cache.delete_memoized for the affected users, inside User.follow and unfollow and at post and user creation, and CACHE_DEFAULT_TIMEOUT bounds the life of any entry a future write path forgets. The new tests prove both the hit and the invalidation.
Does the Docker image change?
No. requirements.txt gains one line, which the Dockerfile already installs, and boot.sh and the Procfile are unchanged. Redis was already a runtime requirement for the task queue.
More Flask jobs
The same job on other stacks
- Add Response Caching to a Hono API (Hono)
- Add HTTP Caching to a Ktor API (Ktor)
- Add Caching to a Quarkus App (Quarkus)