What a Code Index Is, and When You Need One

A code index is a structural map of your repository: every function, class, component and type, where each one is defined, what calls it, which routes reach it, and what your database schema actually looks like. It is a lookup table for questions with exact answers, and it is a different thing from search.

That distinction is the whole point, and it's the part most explanations skip.

Three ways to find code, and what each one can answer

Text search answers where does this string appear. Grep, ripgrep, your editor's find-in-files. It's fast, exact, and completely indifferent to meaning — searching for currency returns the comment, the CSS class, the test fixture, and the variable named currencyCode alongside the function you wanted.

Semantic search answers what looks similar to this description. Chunk the repository, embed the chunks, embed the query, return the nearest neighbours. It's good at "where is the retry logic" when nothing is literally named retry. It's a similarity ranking, so it always returns something, and there's no clean signal distinguishing "here it is" from "here are the five least-unrelated chunks."

A structural index answers where is this defined, and what depends on it. It parses the code rather than the text, so it knows that formatCurrency on line 40 is a definition and the same word in a comment is not.

None of these is better in general. They answer different questions, and confusing them is how you get confident wrong answers.

The question that only structure answers

Here's the one that matters when an AI assistant is writing code for you:

Does a function that does this already exist?

Text search can't answer it — you'd have to guess the name. Semantic search can't answer it either, not really: it returns the closest chunks, and if nothing close exists it still returns the closest chunks. Nothing in the result says "no."

A structural index gets closer than either, and it's worth being exact about how close. What it answers exactly is the naming question: "is there a symbol named X", "is there a symbol whose name contains Y". Those have real answers — including a real "no", which is the part neither of the others can give you.

What it does not do is prove that no equivalent exists under some other name. A toMoney that duplicates your formatCurrency is invisible to a lookup by name, and finding it still takes reading. Structure turns an unbounded question into a small and checkable one. It doesn't turn it into a solved one.

The follow-up question is the one people forget, and structure does answer that one outright:

If I change this, what breaks?

That's a call graph question. Text search finds the word in comments and strings; semantic search finds things that read similarly. Neither gives you the list of callers, which is the only list that matters before you change a signature.

When you need one

Roughly: when your repository has outgrown the point where anyone — human or model — can reliably sample it.

Concretely, you probably need one when:

• It's large enough that nobody knows all of it. Once no single person can hold the map, "I don't think we have that already" stops being reliable evidence.
• You're working with an AI assistant. This is the case that changed fastest. Opening a handful of likely files was fine when a person was choosing each one; it's a different proposition when the assistant is choosing and you can't see what it skipped.
• Changes cross boundaries. Multiple services, a client and an API, more than one repository. The dependencies you most need to see are the ones that leave the file you're looking at.
• Refactoring is the risky part of your work. If "who calls this" is the question that decides whether a change is safe, guessing at it is the expensive habit.

You probably don't need one when the project is small enough to hold in your head, or new enough that there's nothing to rediscover. A few thousand lines you wrote last month doesn't need a map. The tool is for the codebase you inherited, or the one you wrote two years ago and have half-forgotten.

What it doesn't solve

An index tells you what exists and how it connects. It doesn't tell you whether the code is any good, whether the design is right, or what the business logic is supposed to do. It answers structural questions, which are a minority of the interesting questions about a codebase — but they're the ones that get guessed at most often, and guessing costs the most.

It also has to stay current. An index built from last week's code will answer today's question confidently and wrongly, which is worse than not answering. Whatever you use, the thing to check first is how it learns your code changed.

Where cix fits

cix is a structural index — symbols, routes, schema, dependencies — that connects to Claude Code, Codex, and Gemini CLI over MCP, so your assistant can query it while it works rather than inferring your project from whichever files it happened to open. The index is scoped to the branch you're on, and it refreshes as you push.

The two questions at the top of this post — does this already exist, and what calls it — are the ones to try on anything in this category. A tool that answers them with a ranked list of near-matches is doing something else. That something else is often useful; it just isn't this.