What the agent does
The agent reads the API to find where the extra reads come from. In a Worker like the blog example in honojs/examples, src/index.ts builds a Hono app, mounts a middleware router at /api that applies prettyJSON() and basicAuth with USERNAME and PASSWORD from Bindings on every non-GET under /posts/*, and mounts src/api.ts at the same prefix. api.ts registers GET and POST /posts, GET, PUT and DELETE /posts/:id, with cors() on /posts/*, and delegates to src/model.ts. There, posts live in the BLOG_EXAMPLE KV namespace under keys prefixed v1:post:, createPost writes {id, title, body} as JSON with crypto.randomUUID() for the id, and getPosts is the problem: it calls KV.list({ prefix }), then loops over list.keys and calls KV.get(keys[i].name) for each one, awaiting each in turn. For N posts that is one list plus N serial gets, so the list endpoint's latency grows with the number of posts, one round trip at a time. src/api.test.ts runs under @cloudflare/vitest-pool-workers with isolatedStorage: false and walks the five routes in order, asserting posts.length is 0 before a create and 1 after. package.json pins hono at ^4.2.4, wrangler at ^3.53.0 and vitest 1.3.0.
The fix has two parts, and the agent does the safe one first. In getPosts it replaces the serial loop with a single Promise.all over keys.map((k) => KV.get(k.name)), so the N gets go out together and the handler waits once; that keeps the response shape and is enough for a small blog. It also handles list_complete and cursor from the list result, which the current code ignores, so a namespace with more keys than one list page returns no longer silently drops the rest.
The second part removes the gets altogether for the list endpoint. KV.put accepts a metadata object that KV.list returns beside each key without a get, so createPost and updatePost write { title } as metadata alongside the JSON value, and a new listPostSummaries builds {id, title} rows from list.keys[i].metadata alone, in one call per page. GET /posts switches to that summary shape and GET /posts/:id keeps returning the full post with body, which is what a client needs to render a list and a page. Because older keys were written without metadata, listPostSummaries falls back to a get only for keys whose metadata is missing, and the pull request notes that a one-off re-put of existing posts removes the fallback path.
The agent updates api.test.ts so the list assertions check id and title and adds cases for a key written without metadata and for a two-page list, which it builds by putting more keys than the limit it passes to list in the test. It runs vitest --run in the Worker pool, then wrangler dev with a local KV namespace to call the endpoints with curl and compare the response for the old and new getPosts, and pastes both the test output and a short before-and-after of the request log into the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Fix the N+1 KV reads in the list endpoint of this Hono API and open a pull request. Read package.json, wrangler.example.toml, vitest.config.ts, src/index.ts, src/api.ts, src/bindings.ts, src/model.ts and src/api.test.ts first. In model.ts, getPosts lists keys with a prefix and then awaits one KV.get per key in a loop. First replace the loop with Promise.all over the keys and handle list_complete and cursor so every page is read. Then store { title } as metadata on every put in createPost and updatePost, add listPostSummaries that builds { id, title } rows from list metadata without a get, falling back to get only for keys with no metadata, and switch GET /posts to return those summaries while GET /posts/:id keeps returning the full post. Update api.test.ts for the new list shape and add cases for a key with no metadata and for a list that spans two pages. Run vitest --run, then wrangler dev with a local KV namespace and call the endpoints with curl. Paste the test output and a before-and-after of the list request in the pull request. Do not change the auth middleware or the other routes.",
"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 that edits src/model.ts, src/api.ts and src/api.test.ts and touches neither src/index.ts nor the auth middleware. The description explains the two steps, parallel gets and metadata-backed summaries, shows the new GET /posts response shape beside the old one, pastes the vitest output with the new cases named, and includes the curl calls against wrangler dev so a reviewer can see the shape change rather than infer it.
A repository with a CI job that runs npm test in the workspace runs the Worker-pool tests on the pull request. The run's record keeps the wrangler dev session and every request made against it.
A reviewer checks that no client depends on body in the list response before the shape changes, that the metadata stays under KV's per-key metadata limit for the fields chosen, and that the fallback get for keys without metadata is temporary. If the shape change is not acceptable, the first step alone, Promise.all plus paging, still ships and the second can wait.
Run it on every Hono service that lists from KV
A team with several Workers sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own model.ts, so a service that already stores metadata gets only the paging fix and a service that lists from two prefixes gets both handled, and each run opens its own pull request. Send a request_id per request so a retried call returns the run it already started.
Give the key a webhook_url and every run it starts posts run.completed when its turn ends, with data.session_url to read the pull request link and the test output from.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A serial-read bug is quiet in a test with one post and loud in production with a thousand, and the honest check is to run the Worker locally, write enough keys to cross a list page, and watch the request. In a Rush sandbox the agent runs vitest in the Workers pool, starts wrangler dev with a local namespace, writes the keys, calls the endpoint before and after, and keeps every command and response in the run's record.
The result is a branch with the fix in two separable steps and a pull request that shows the response shape change in the open, so the reviewer can take the conservative half if the API contract must hold. The same request works on any Hono or plain Workers service whose list handler follows a list with a get per key.
Frequently asked questions
Does Promise.all alone fix it?
It fixes the latency, since the gets go out together instead of one after another, and the paging fix stops dropped keys. It does not reduce the number of KV reads, which still grows with the number of posts and is billed per read. The metadata step is what brings the list endpoint down to one read per page.
Why change the response shape of GET /posts?
KV metadata is small by design, so it can carry a title but not a post body. Returning {id, title} from the list and the full post from GET /posts/:id is the shape most clients want, and the pull request shows it explicitly. A team that must keep body in the list keeps the first step and skips the second.
What about posts written before metadata existed?
The summary function falls back to a get for any key whose list entry has no metadata, so nothing disappears from the list. The pull request suggests a one-off script that re-puts each existing post with its metadata, after which the fallback never runs.
Will the existing tests still pass?
The create, read, update and delete cases pass unchanged. The two list cases change because the list rows no longer carry body; the agent updates those assertions and adds the two new cases, and the vitest output in the pull request shows all of them.
More Hono jobs
The same job on other stacks
- Fix N+1 Queries in a Laravel App (Laravel)
- Fix N+1 Queries in a Phoenix App (Phoenix)
- Fix N+1 Queries in a Rails App (Rails)