What the agent does
The agent clones the repository into its own cloud sandbox and lists every query call before touching the version. In a React dashboard like haishanh/yacd, package.json pins @tanstack/react-query at 4.35.3 with React 18.2.0, TypeScript 5.2.2 and Vite 4.4.9, and the pnpm-lock.yaml is a version 6 lockfile that needs pnpm 8. The search finds the v4 array form in four places: useQuery([ENDPOINT.config, apiConfig], fetchConfigs2) in src/store/configs.ts, useQuery(['/version', apiConfig], fetchVersion) in src/components/about/About.tsx, and two more in src/components/rules/rules.hooks.tsx, which also calls useMutation(refreshRuleProviderByName, { onSuccess }) twice and reads isLoading from it, and queryClient.invalidateQueries(['/providers/rules']) with a bare key, as src/components/Root.tsx does once. src/misc/query.ts sets defaultOptions.queries.suspense: true, which is why the components read data without null checks. src/components/Config.tsx already uses the object form for its mutation.
Then it reproduces both failures. tsc --noEmit is clean at 4.35.3. After pnpm add @tanstack/react-query@5, it reports errors of six kinds: TS2769 No overload matches this call at the array-form useQuery calls, TS2559 where a string[] is passed as InvalidateQueryFilters or a function as UseMutationOptions, TS2339 such as Property 'isLoading' does not exist on type 'UseMutationResult' and Property 'names' does not exist on type 'unknown' downstream of the now untyped data, TS2345, TS2322 on suspense, and TS2740 in Config.tsx where data is no longer known to be defined. The runtime side is a hard stop: rendering a component that calls useQuery(['/version', apiConfig], fn) on v5 throws Error: Bad argument type. Starting with v5, only the "Object" form is allowed when calling query related functions. Please use the error stack to find the culprit call., from the check at useBaseQuery.js line 25 in the installed package.
The agent tries the published codemod first and finds that this release ships none: there is no build/codemods directory in the installed @tanstack/react-query 5 release and no @tanstack/query-codemods package on npm, so it rewrites the seven files by hand. useQuery([k, apiConfig], fn) becomes useSuspenseQuery({ queryKey: [k, apiConfig], queryFn: fn }), because v5 removed the suspense option and useSuspenseQuery is what keeps data defined for the components that rely on it; useMutation(fn, { onSuccess }) becomes useMutation({ mutationFn: fn, onSuccess }) and isLoading becomes isPending; invalidateQueries(['/rules']) becomes invalidateQueries({ queryKey: ['/rules'] }); and the suspense: true default is deleted from query.ts. The fetchConfigs2, fetchVersion, fetchRules and fetchRuleProviders functions already take the { queryKey } context object, so they need no change.
It proves the migration two ways. tsc --noEmit reports no errors, including the Config.tsx and Rules.tsx lines that only failed because data had lost its type, and vite build completes, writing the app and its service worker. The agent runs the same render on the rewritten About hook and gets markup instead of the thrown error. The diff spans seven files, lockfile included, with no shim or wrapper added.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade @tanstack/react-query from v4 to the current v5 release. Read package.json and list every useQuery, useMutation, useQueries, useInfiniteQuery and invalidateQueries call first, and note any defaultOptions the QueryClient sets. Run the TypeScript check on v4, install v5, run it again and quote the error counts by code, then render one array-form call on v5 and quote the runtime error. Use the official codemod if the installed release ships one, otherwise rewrite each call to the object form by hand: queries that relied on a suspense default become useSuspenseQuery, mutations take mutationFn and read isPending, invalidateQueries takes a queryKey filter. Run the TypeScript check and the production build afterwards and quote both. Open a pull request with the before and after.",
"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 touching package.json, the lockfile and five source files: src/misc/query.ts, src/store/configs.ts, src/components/about/About.tsx, src/components/rules/rules.hooks.tsx and src/components/Root.tsx. The description lists the TypeScript errors by code from the v5 install, quotes the Bad argument type runtime error with the line in the installed package that throws it, and shows tsc --noEmit clean and vite build finishing afterwards.
A reviewer checks the two decisions that are not renames: useSuspenseQuery in place of a global suspense default, which keeps the existing Suspense and ErrorBoundary in Root.tsx doing the same work, and isPending in place of isLoading on the mutations, whose meaning v5 changed. The run's record holds each tsc, render and build with its full output, so the errors and the clean run can be opened rather than taken on trust.
Run it on every Monday morning
Add an automation to the Project with this prompt and a schedule trigger, cron set to 0 9 * * 1 in your timezone. Each Monday one run bumps the query library, typechecks, builds and opens one pull request on its own branch; a week where a call has no object-form equivalent the agent can prove ends needs_review with the error attached, and a week already on the current major opens nothing.
The same body works from your own code with POST /o/{org}/sessions and an API key when a dependency bot's @tanstack/react-query bump turns red; the key's webhook_url receives run.completed or run.failed with the session URL and the pull request when the run ends.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A major version of a data library breaks in three layers at once: the types, the runtime check, and the semantics underneath, such as a removed suspense option that silently made data optional. The agent runs the typecheck, a render and the build in its sandbox at the old and new versions, keeps each run in the run's record, and the pull request shows the errors going to none and the thrown Bad argument type going to rendered markup.
Migration guides promise a codemod, and the agent checks whether the installed release actually ships it rather than assuming. When it does not, the hand rewrite is bounded by the list it made first, seven files, and every change is one of three documented substitutions, so the reviewer reads a short diff instead of a tool's output.
Frequently asked questions
What is the object form?
v5 removed the overloads that took a key, a function and options as separate arguments; every query function takes one options object with queryKey, queryFn and the rest. The runtime check that throws Bad argument type exists so an array-form call fails at once instead of silently fetching nothing.
Why useSuspenseQuery instead of useQuery?
The app set suspense: true as a client default, which v5 removed. useSuspenseQuery suspends the same way and types data as defined, which is why the downstream Property 'names' does not exist on type 'unknown' errors disappear without adding null checks to every component.
What changed about isLoading?
On mutations, v5 renamed isLoading to isPending. On queries, isLoading still exists but now means pending with no data yet, and the old meaning is isFetching; the agent reads each use before choosing.
Will it install the codemod package?
It looks for one: the TanStack repository keeps codemods in its own package, and the installed 5.x release had none on npm. If your version ships one, the agent runs it and then does the typecheck and build the same way, because the codemod does not cover the suspense default or isPending.