chatgpt-your-files: a workshop repo that builds a pgvector RAG app in six git checkpoints

What chatgpt-your-files actually ships, and what it does not

The subtitle in the README is literal: this is a workshop called pgvector to Prod in 2 hours, and the whole thing was recorded as a YouTube video linked from the repository. The stated goal is to create a production-ready MVP for securely chatting with your documents. The feature list covers an interactive chat interface driven by OpenAI models and retrieval augmented generation, third party login through what the README calls any of our 18 auth providers plus user and password, document storage, a REST API, and row-level security on user data.

What it does not ship is a package. There is no npm install chatgpt-your-files step anywhere in the material, no published release, and the last push timestamp is the only signal about activity. The README's own framing is that you clone at a tag and follow along. That distinction matters more than it sounds: the artefact is a sequence of checkpoints, and the code at step-4 is not the same code as the code at step-1. If you evaluate it as a library you will be disappointed by the absence of a version, a changelog and a licence identifier. If you evaluate it as a guided build, the structure is the point.

The audience is therefore narrow but real. A developer who already knows Next.js and Postgres and wants to see how Supabase wires storage, embeddings and access control together gets a complete path. A developer looking for a component to paste into an existing product gets nothing, because the integration points are the tutorial's subject matter rather than its output.

The git-tag checkpoint model and why it shapes everything else

The workshop is divided into numbered steps, each a git tag. The README instructs you to clone at step-1 to get the starting point, and then to move between checkpoints with a stash and a checkout. The listed steps are Storage, Documents, Embeddings, Chat, and a bonus step on Database Types. Step 0 is marked optional and is described as equivalent to running npx create-next-app -e with-supabase, with additions for VS Code settings and UI scaffolding.

This is a specific and slightly unusual distribution model. It means the repository has no single canonical state that represents the finished product in a way you can consume blindly. To see the finished app you have to reach the final checkpoint, and the README's jump list is the map. It also means that if you fork the repository and commit your own work on top of a tag, you inherit a detached-HEAD situation unless you branch first. The README does not address that, and it is the first thing that will trip up anyone who follows the instructions without thinking about git state.

The checkpoint approach has a second consequence. Because each step is meant to be a self-contained teaching moment, the intermediate states are deliberately incomplete. If you check out step-2 expecting a working chat, you will not find one. That is fine for a workshop and confusing for anyone who lands on the repository through a search and assumes main is the finished article. The README does not say what main contains relative to the tags, and the supplied material does not resolve it.

How the pieces connect: storage, embeddings, Edge Functions and RLS

The architecture visible in the material is a Next.js frontend on top of a Supabase project, with OpenAI called from Supabase Edge Functions. The README describes Supabase Storage as built-in object storage backed by S3 that integrates directly with the Postgres database. That integration is what makes the rest of the design possible: a file lives in a bucket, and a row describing that file lives in a table, so the same row-level security policies that guard rows can be used to reason about who may read the object.

The Edge Functions are where the external calls happen. The README has you create supabase/functions/import_map.json listing the Deno dependencies, and the contents are informative about the intended design: @supabase/supabase-js, openai, common-tags, the ai package, and a cluster of markdown utilities (mdast-util-from-markdown, mdast-util-to-markdown, mdast-util-to-string, unist-builder, and the mdast types). The presence of that markdown toolchain is the clearest signal about how documents are handled. Rather than splitting raw text on character counts, the workshop appears to parse markdown into an AST and work from the tree structure, which is a more careful approach to chunking prose than a naive splitter. The sample data reinforces this: the repository includes three markdown files about the Roman empire for testing.

The ai package in that import map is worth noting for anyone planning to follow along today. It is pinned to a specific esm.sh version, and the OpenAI client alongside it is pinned to 4.10.0. Pinned Deno imports are reproducible, which is good for a workshop, but they also mean the code reflects the API surface of those versions rather than the current one. Expect to adjust model identifiers and possibly response handling if you build past the final checkpoint.

Getting it running: the commands the README gives

Prerequisites are stated plainly: a Unix-based OS (WSL2 on Windows), Docker, and Node.js 18 or later. Clone at the first checkpoint with git clone -b step-1 https://github.com/supabase-community/chatgpt-your-files.git. The Supabase CLI is installed as a dev dependency at a pinned version with npm i -D supabase@1.102.0, then initialised with npx supabase init.

For local development the sequence is npx supabase start, which the README notes runs in Docker, followed by writing credentials into .env.local. The command given for that is a pipeline: npx supabase status -o env with --override-name api.url=NEXT_PUBLIC_SUPABASE_URL and --override-name auth.anon_key=NEXT_PUBLIC_SUPABASE_ANON_KEY, piped through grep NEXT_PUBLIC into .env.local. That is a neat trick and worth copying, but note that it writes only the two public variables. Anything server-side that needs a service role key is not covered by that grep, and the README does not show where it goes.

The cloud path starts with creating a project at database.new or through the CLI with npx supabase projects create. The supplied README text is truncated mid-command at that point, so the full argument list is not available here and I will not guess at it. The frontend scaffolding uses shadcn/ui: npx shadcn-ui@latest init with prompts for TypeScript, the Default style, the Slate base colour, app/globals.css as the global stylesheet, CSS variables enabled, tailwind.config.js as the Tailwind config, @/components and @/lib/utils as import aliases, and React Server Components enabled. Components are added with npx shadcn-ui@latest add button input toast, and the extra runtime dependencies are @tanstack/react-query and three-dots.

The security story is the reason to read this repo, and also its thinnest documented part

Row-level security is listed as a headline feature and described as securing all of your user data. The claim is credible in outline: Supabase RLS is enforced by Postgres, and the whole point of putting documents in Storage alongside rows in Postgres is that one policy model can cover both. But the README as supplied does not show a single policy definition. The policies live in the migration files that the workshop walks through on video, and the written material here does not reproduce them.

That gap is the main practical risk. If you follow the steps and copy the migrations, you get whatever the presenter wrote, and you have to read those migrations yourself to know what they permit. RLS that is too permissive and RLS that is absent look identical from the outside until something leaks. Anyone adopting this pattern for real user documents should read the policy SQL line by line rather than trusting the feature bullet. The same applies to the auth layer: the README mentions 18 providers and user/password, but the configuration that decides which providers are actually enabled lives in the Supabase dashboard or config, not in the text supplied.

There is a design tension worth naming. The REST API is described as flexible and consumed by the frontend, and the frontend is a Next.js app with React Server Components enabled. That gives you at least two paths to the same data (server components and API routes) and the security properties differ between them depending on which key is used. The workshop's video presumably resolves this; the README alone does not.

Where this is the wrong tool, and what to use instead

This is the wrong choice if you need a maintained RAG library with a stable API. The README contains no release notes, the repository listing shows no retrieved releases, and there is no licence identifier in the supplied material. For a production dependency that is a blocker, not a detail. It is also the wrong choice if your documents are not markdown. The dependency list is built around mdast parsing, and the sample files are markdown. Feeding PDFs or HTML through this pipeline means replacing the parsing stage, which is a meaningful fraction of the work the workshop is teaching.

A real alternative in the same ecosystem is to use Supabase's own vector tooling directly without the workshop scaffolding: enable the pgvector extension, define your embedding table, and write the retrieval query yourself. The difference in approach is that the workshop gives you a specific application shape (Next.js, shadcn/ui, Edge Functions, a chat UI) and you inherit its choices, while the direct route gives you only the database primitive and leaves the application architecture to you. If your product is not a chat interface, the direct route avoids carrying a UI you will delete.

On the retrieval side specifically, the workshop's chunking strategy is markdown-structure-aware. A generic splitter that cuts on token counts is simpler to implement and works on any text format. The trade-off is real in both directions: structure-aware chunking preserves headings and lists as units, which tends to produce more coherent retrieved passages, but it requires a parser per format and fails quietly on malformed input. If your corpus is uniform, the parser is worth it. If it is heterogeneous, the simpler splitter is the more honest choice.

Maintenance cost and the licence question

The dependencies are pinned aggressively, and that is the maintenance story in one sentence. The import map fixes @supabase/supabase-js at 2.21.0, openai at 4.10.0, ai at 2.2.13, and the mdast packages at their 2.x and 4.x lines, all resolved through esm.sh with a v132 path prefix. Deno std is pinned at 0.168.0. That reproducibility is a virtue for a workshop that must still work when someone watches the video a year later. It is a cost for anyone building on top, because upgrading any one of those means checking the others, and the OpenAI client in particular has moved on since 4.10.0.

The Supabase CLI is pinned at 1.102.0 as a dev dependency, which means the local stack behaviour is tied to that CLI version. Newer CLI versions change flags and output formats, and the .env.local pipeline in the README depends on the exact shape of npx supabase status -o env. If you bump the CLI, re-run that command and check the output before trusting the grep.

On licensing, the supplied material does not state a licence. The repository listing shows the field as unknown and the README contains no licence section. I cannot tell you what terms apply, and I will not speculate. Read the LICENSE file in the repository root before you copy migrations, Edge Functions or UI components into anything you intend to distribute, and if the file is absent, ask the maintainers directly. That is a factual gap in this review, not a legal opinion, and it is the single most important thing to resolve before reuse.

Editorial conclusion

Adopt this if you are learning how Supabase Storage, pgvector embeddings, Edge Functions and row-level security fit together, and you are willing to work through git tags rather than install a package. Do not adopt it if you need a maintained library with a release history, a versioned API or a stated licence, because none of those are visible in the repository material. Before committing, verify three things yourself: the licence file in the repo root, the exact OpenAI model names your account can call, and whether the row-level security policies in the migrations cover the tables you plan to add.

Official sources

1. Issues
2. Project website
3. README
4. supabase-community/chatgpt-your-files on GitHub