What the agent does
The agent first finds where the generated types live and who depends on them. In a template like Razikus/supabase-nextjs-template, nextjs/src/lib/types.ts is the output of supabase gen types: a Json alias, a Database type with an __InternalSupabase block recording PostgrestVersion: "12.2.3 (519615d)", a graphql_public schema with one graphql function, and a public schema whose only table is todo_list with Row, Insert and Update shapes for id, title, description, urgent, done, done_at, owner and created_at, followed by the Tables, TablesInsert, TablesUpdate, Enums and CompositeTypes helper generics and a Constants object. Four client files import it: lib/supabase/client.ts and server.ts call createBrowserClient<Database, "public", Database["public"]> and createServerClient with the same parameters, serverAdminClient.ts uses the service key, and lib/supabase/unified.ts wraps them in a SassClient whose createTask takes Database["public"]["Tables"]["todo_list"]["Insert"]. app/app/table/page.tsx derives Task and NewTask from the same path. A second copy lives in supabase-expo-template/lib/types.ts for the mobile app, generated by an older CLI: no __InternalSupabase block and a PublicSchema alias where the web copy says DefaultSchema.
Then it reads the schema the types are supposed to describe. supabase/config.toml names the project sasstemplate, exposes public and graphql_public through the API on port 54321, runs Postgres 15 on 54322, and enables seeding from ./seed.sql, a file that does not exist in the repository. supabase/migrations has four files: 20250107210416_MFA.sql creates the authenticative schema and a SECURITY DEFINER function is_user_authenticated that reads the JWT's aal against verified MFA factors; 20250130165844_example_storage.sql inserts a private files bucket; 20250130181110_storage_policies.sql adds four policies on storage.objects scoped to a folder named after auth.uid(); and 20250130181641_todo_list.sql creates todo_list with row level security, grants to anon, authenticated and service_role, and a policy that requires authenticative.is_user_authenticated() and owner = auth.uid(). migrations_for_old holds the earlier versions and the auth_removal migration that moved the function out of the auth schema. The nextjs app has dev, build, start and lint scripts but no type-check script, tsconfig.json is strict, and .github holds only a funding file, so nothing checks any of this today.
The regeneration itself runs in the sandbox against a local stack. The agent runs supabase start, which needs Docker, then supabase db reset to apply the four migrations in order, noting the warning about the missing seed.sql. It runs supabase gen types typescript --local --schema public --schema graphql_public and writes the result to nextjs/src/lib/types.ts, then diffs it against the committed file: a different PostgrestVersion line is expected whenever the CLI version differs and is not drift, while a changed column, a new table or a missing function is. It writes the same output to supabase-expo-template/lib/types.ts so the two apps share one generated file, and checks that createClient<Database> in the Expo app's lib/supabase.ts still compiles against the newer helper names. In nextjs it adds a check-types script that runs tsc --noEmit and runs it, and runs npx tsc --noEmit in the Expo folder, since a regenerated Insert type is where a hand-written createTask call breaks.
The lasting part is a workflow, .github/workflows/supabase-types.yml, that runs on pull requests touching supabase/migrations/**, supabase/config.toml or either types.ts: it installs the CLI with supabase/setup-cli, runs supabase db start and supabase db reset, regenerates into both paths, fails with git diff --exit-code when the committed types differ, ignoring the PostgrestVersion line, and then runs yarn check-types in nextjs. The agent pins the CLI version in the workflow so the header stays stable from run to run, and writes the one-line regeneration command into the pull request so a developer who adds a migration knows what to run.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Regenerate this repository's Supabase TypeScript types from its migrations and add a check that keeps them in sync. Read supabase/config.toml, every file under supabase/migrations, nextjs/src/lib/types.ts, the files under nextjs/src/lib/supabase that import it, nextjs/package.json and tsconfig.json, and supabase-expo-template/lib/types.ts and lib/supabase.ts first. Start the local stack with supabase start and apply the migrations with supabase db reset, noting any warning about a missing seed file. Run supabase gen types typescript --local --schema public --schema graphql_public and write the output to nextjs/src/lib/types.ts and to supabase-expo-template/lib/types.ts. Diff each against the committed file and separate a PostgrestVersion header change from a real schema difference. Add a check-types script to nextjs/package.json that runs tsc --noEmit and run it; run tsc --noEmit in the Expo folder too; fix any call that the regenerated Insert or Row types no longer accept, with the smallest change. Add .github/workflows/supabase-types.yml that runs on pull requests touching supabase/migrations/**, supabase/config.toml or either types file: install a pinned Supabase CLI, run supabase db start and supabase db reset, regenerate into both paths, fail with git diff --exit-code when they differ other than the PostgrestVersion line, then run yarn check-types in nextjs. Do not change any migration or policy. Open a pull request that pastes the diff summary for each types file, names the CLI version you pinned, quotes the gen and tsc commands with their output, and states the one command a developer runs after adding a migration.",
"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 the regenerated nextjs/src/lib/types.ts, the Expo copy brought to the same output, a check-types script in nextjs/package.json, a new .github/workflows/supabase-types.yml, and any call site that the regenerated types no longer accepted, changed minimally. The body pastes the diff summary for each types file, separating the PostgrestVersion header from schema differences, names the pinned CLI version, and quotes the supabase gen types and tsc --noEmit commands with their output.
The new workflow runs on the pull request itself, because the types files are in its path filter, and that first run is the proof that the committed output matches what the pinned CLI generates from the four migrations. From then on a pull request that adds a migration without regenerating fails on git diff --exit-code with the missing lines shown, and one that changes a column the app writes to fails on check-types with the file and line.
A reviewer reads the schema part of the diff against the migrations, confirms no migration or policy changed, and checks that the ignore for the header line is narrow enough that a real change to the __InternalSupabase block would still be caught. The missing seed.sql is noted for them to add or to remove from config.toml.
Run it on every pull request that changes a migration
Add an automation to the Project that holds the repository with this prompt and a github trigger on pull_request.opened and pull_request.synchronize. The trigger appends the pull request event after the prompt, so the agent reads the branch from it, regenerates the types on that branch and pushes the result as a commit, which the new workflow then checks. Pull requests from forks never fire. max_runs_per_hour on the automation caps how many pull requests it handles in an hour, each in its own sandbox with its own local Supabase stack.
From your own server, a handler for GitHub's pull_request webhook that sees a changed path under supabase/migrations sends POST /o/{org}/sessions with this prompt and the branch written into input, the repository in resources, and a request_id that is a UUID v5 of the head commit so a redelivery returns the run it already started. A webhook_url on the key receives run.completed with data.session_url when the turn ends.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Generated types drift quietly: a migration lands, types.ts keeps describing the old table, and the mismatch shows up as a runtime error in a query that type-checked. Regenerating needs a running Postgres with the migrations applied and the exact CLI version, which on a laptop means Docker, ports and a version that differs from a colleague's. In a Rush sandbox the agent starts the stack, applies the four migrations, generates, diffs and type-checks, and the transcript holds the commands and the diff.
Two copies of the same generated file, for a web app and a mobile app, double the chance of drift. One run brings both to the same output and leaves a workflow that fails the next time they diverge, so the check is in CI rather than in someone's memory.
Frequently asked questions
Why does the PostgrestVersion line change?
The CLI writes the PostgREST version of the local stack into the __InternalSupabase block, so a newer CLI produces a different line with no schema change behind it. The workflow pins the CLI version and ignores that one line in its comparison; any other difference, including a changed helper type, still fails the check.
Does it generate against my hosted project instead?
No. The migrations in supabase/migrations are the source of truth, and generating from a local supabase db reset means the types describe what the repository says, not what someone changed in the dashboard. A difference between the two is worth knowing about, and would show when the hosted project is next diffed against the migrations.
What about the missing seed.sql?
config.toml enables seeding from ./seed.sql, which is not in the repository, so supabase db reset warns and continues. The agent does not create the file, since seed data is a product decision, and notes the warning in the pull request so the team can add the file or turn the setting off.
Will the Expo app break when its types change shape?
The Expo copy was generated by an older CLI and uses different helper names, so the agent runs tsc --noEmit in that folder after replacing it. lib/supabase.ts only passes Database to createClient, and any screen that used the old helper names is adjusted in the same pull request with the compiler output quoted.