What "codebase-aware" AI generation actually means

"Codebase-aware" has started showing up in a lot of AI builder marketing. So has "import your repo." They get used almost interchangeably, and they shouldn't be — importing a repository and understanding it are two different jobs, and most of what ships today only does the first one.

Import gets code into the room. It doesn't read it.

Look at what "import" actually does in the tools that offer it. Lovable's GitHub import boots your repo in a sandbox, installs dependencies, and gets a preview running — then keeps a sync going so changes in Lovable push back to your main branch. Vercel's v0 added repo import so it can pull your code and your Vercel environment variables into a chat, then let you branch, push, and open PRs against it. Both are genuinely useful — they solve the plumbing problem of getting your code and an AI agent into the same sandbox.

Neither step, as documented, is an architectural read of the repo. There's no described stage where the tool builds a model of your component structure, your design tokens, or which patterns are conventions versus which are one-offs. Import means "the files are now reachable," not "the tool knows what they mean." That's a reasonable scope for what those features are built to do — but it means the generation step that follows still has to figure out your codebase from scratch, in-context, one prompt at a time.

That gap is where "codebase-aware" is supposed to live, and it's worth being precise about what closing it actually requires.

What understanding a codebase requires

Three things have to happen before a generation step can be said to understand a repo, not just have access to it:

Exploration. Something has to walk the repo the way an engineer onboarding to a new project would — following imports, checking how components compose, noticing which folder actually holds the design system versus which one is legacy. A flat directory listing or a single embedding pass over every file doesn't capture that; structure matters as much as content.

Retrieval built for code, not prose. General-purpose text embeddings are tuned for natural language similarity. Code has different structure — imports, types, call graphs — and retrieval that doesn't account for that tends to surface files that look related by keyword rather than files that are actually relevant to the thing being built.

A structured summary that generation can actually use. Exploration output that lives only as scratch reasoning gets lost by the time the model is asked to write new code. It needs to collapse into something concrete — which framework, which components exist, which tokens are canonical, which of several possible approaches fits this repo — so every subsequent generation call is working from the same brief instead of re-deriving it.

Skip any of the three and you get output that's plausible-looking but doesn't fit: a new component that duplicates one that already exists, styling that's close to your tokens but not equal to them, a pattern that works but isn't how the rest of the repo does things. That's usually what "the AI didn't understand my codebase" actually means in practice — not that the model is bad at code, but that nothing upstream of it did the understanding step at all.

How Shipd does this

Shipd's codebase-aware pipeline runs all three stages before a single line of new code gets written:

• Agentic exploration. A Claude-Code-style tool loop reads your repo the way an engineer would — following imports and structure rather than pattern-matching on file names.
• Code-specialized retrieval. Your code is embedded with Voyage's voyage-code-3 model into a 1024-dimensional pgvector index, using asymmetric query/document search built for code rather than generic prose similarity.
• An Architecture Brief. Exploration output collapses into a concrete brief — framework, detected components, design tokens, and a recommended fit mode — that drives every generation from that point on.

You connect a repo (GitHub authorization or a ZIP upload — nothing leaves your Git host either way) and get back a brief showing what was found: framework, component count, chunks indexed, retrieval status. From there you choose how closely a build should hug what's already there:

• Style-match — generate fresh code that fits your look and patterns without importing your actual components.
• Vendor — import and reuse your real components, so output drops into your app instead of sitting next to it.
• Repo — generate against the whole repository, wiring directly into existing modules and structure.

The point of separating these is that "understands your codebase" isn't one setting. Sometimes you want output that merely looks consistent; sometimes you need it to literally reuse what you've already built. Both are legitimate, and conflating them is part of why "codebase-aware" has gotten mushy as a term.

The test that actually matters

Ignore the marketing copy and ask a narrower question: after the import step, does anything happen before generation that could plausibly be called reading the code — as opposed to just making it available? If the honest answer is "the model sees the files in context and does its best," that's a capable AI builder with repo access. It is not, by any precise use of the term, codebase-aware. The difference shows up immediately in the output: whether the third component you generate looks like the first one you already had, or like something new that happens to share a color palette.