DEV Community

Cover image for Codebase Search: How Agents Find Code
Tomer Raitz for Vibki

Posted on Originally published at vibki.com

Codebase Search: How Agents Find Code

Originally published on vibki.com.

Have you ever asked your AI agent for a function and got a copy of an existing one? Codebase search is how the agent finds code without reading your whole repo: by text, by meaning or from a map of function names. By the end you will point your agent at code it would miss.

Does your AI agent really read your whole repo?

No. An average one-year project is about 500 - 1000 files of code, far more than fits in the context window, the amount of text a model can read at once. Can you carry a library to your desk? Neither can your agent, so it opens a few files and writes from those, and code it did not find does not exist for it.

Our running task: "Add a function that shows how long ago a post was published, like '3 hours ago'." The repo already holds four, so missing them means a fifth copy.

How does codebase search pick the few files your agent opens?

The agent avoids that fifth 'x ago' copy only if its search finds the existing four. That search is codebase search: the agent finds code, opens it and writes from it. Aider, an AI coding tool, lists the steps in its blog post "Building a better repository map with tree sitter": find the code, understand it, change it. The agent finds code three ways, each a tool it calls (see our tool calling post). Text search matches the letters you give it, like Ctrl+F across the repo. Meaning search matches what code does. A repo map lists every file with its function names, like a table of contents.

You steer all three like this:

  1. Search the repo for an existing function before writing a new one.
  2. Describe what the code does, not just its name.
  3. Say which folder to look in.

Is plain text search really too dumb for the job?

The oldest codebase search is grep, which prints every line that contains the letters you give it, with no setup, like reading only shelf labels. The reports below come from a stand-in script, not a live model, but the searches on the Vibki frontend are real. Here is the plain task:

Add a function that shows how long ago a post was published, like '3 hours ago'.
Enter fullscreen mode Exit fullscreen mode
--- report
Searched: git grep -il timeAgo -> 0 files
Nothing like it exists. Writing a new function.
Before: 1 new function, a fifth 'x ago' copy.
Enter fullscreen mode Exit fullscreen mode

The agent guessed timeAgo, found 0 files and wrote copy five. Fix 1 adds our first sentence:

Add a function that shows how long ago a post was published, like '3 hours ago'. Before you write any new function, search the repo for one that already does it and tell me what you found.
Enter fullscreen mode Exit fullscreen mode
--- report
Searched: git grep -il timeAgo -> 0 files
Searched: git grep -il ago -> 20 files, 9 with the whole word
Opened 4 non-test files, found 4 functions that print 'ago':
  - formatTimestamp  (components/layout/Comments/utils.Comments.ts)
  - formatRelativeDate  (lib/analytics/adminUsersFormat.ts)
  - formatUpdatedAgo  (lib/analytics/format.ts)
  - formatRelativeTime  (lib/blog/blogUtils.ts)
Reusing formatRelativeTime from lib/blog/blogUtils.ts.
After: reused formatRelativeTime from src/lib/blog/blogUtils.ts, 0 new functions.
Enter fullscreen mode Exit fullscreen mode

The line forced a second guess. What did "ago" find? 20 files, only 9 with the whole word, because text search matches letters, not meaning, so it works only when a guess hits.

💡 Note: the stand-in follows fixed rules. A real model judges.

Can an agent search by meaning instead of by words?

Yes, an embedding is a list of numbers that places text on a map where similar meanings sit close, like books shelved by topic. The agent cuts code into chunks and stores each chunk's numbers in an index, a lookup table. Then it turns your question into numbers the same way and returns the nearest chunks. Cursor's research team measured this in its own agent: in the post "Improving agent with semantic search", Stefan Heule, Emily Jia and Naman Jain report 12.5% higher accuracy on average, and 2.6% more code that stays in repos of 1,000+ files. Fix 2 describes the behaviour:

Add a function that shows how long ago a post was published, like '3 hours ago'. I need what turns a post's timestamp into a phrase like '3 hours ago'. Search by what the code does, not by its name.
Enter fullscreen mode Exit fullscreen mode
--- report
Index: 278 function chunks from 134 files (built once, stale after edits).
Nearest to your description:
  - formatRelativeTime  (lib/blog/blogUtils.ts)
  - formatRelativeDate  (lib/analytics/adminUsersFormat.ts)
  - formatDelta  (lib/analytics/format.ts)
  - formatBestDay  (lib/analytics/format.ts)
Reusing formatRelativeTime from lib/blog/blogUtils.ts.
After: reused formatRelativeTime from src/lib/blog/blogUtils.ts, 0 new functions.
Enter fullscreen mode Exit fullscreen mode

Sounds heavy? It is: you rebuild the index after edits, and it finds similar, not exact: two of four hits here are noise.

💡 Note: a fixed word table stands in for a real embedding model.

What is a repo map, and does your agent have one?

Without an index, your agent can still use a repo map, a short list of every file with its function names and what each takes and returns, like a library floor plan. The Aider docs page "Repository map" says Aider by default keeps only the most referenced names that fit in 1k tokens, the small chunks of text a model reads. The Aider blog post "Building a better repository map with tree sitter" says it builds that map with tree-sitter, a parser that reads code into its parts. Fix 3 names the folder:

Add a function that shows how long ago a post was published, like '3 hours ago'. The date helpers live in src/lib, look there first.
Enter fullscreen mode Exit fullscreen mode
--- repo map, src/lib/blog (a simple stand-in for tree-sitter):
lib/blog/blogUtils.ts:
  formatPostDate(dateString: string): string
  formatRelativeTime(dateString: string): string
  truncateText(text: string, maxLength: number): string
  truncateAtWord(text: string, maxLength: number, ellipsis: string = '…'): string
Enter fullscreen mode Exit fullscreen mode
--- report
Map of src/lib: 126 functions in 33 files.
Names that look like date helpers: 6:
  - formatRelativeDate  (lib/analytics/adminUsersFormat.ts)
  - formatFullDate  (lib/analytics/adminUsersFormat.ts)
  - formatUpdatedAgo  (lib/analytics/format.ts)
  - formatPostDate  (lib/blog/blogUtils.ts)
  - formatRelativeTime  (lib/blog/blogUtils.ts)
  - tutorialAsRelatedCandidate  (lib/tutorials/tutorialUtils.ts)
Reusing formatRelativeTime from lib/blog/blogUtils.ts.
After: reused formatRelativeTime from src/lib/blog/blogUtils.ts, 0 new functions.
Enter fullscreen mode Exit fullscreen mode

Big repos keep only their most referenced names, so you can lose a helper nobody imports, and a map shows names, not behaviour.

Conclusion

So does your agent read the whole Vibki repo before writing the "3 hours ago" function? No: like a librarian, your agent uses codebase search to find code by text, by meaning or from a map. Cursor's research team, in its post "Improving agent with semantic search", says grep together with search by meaning works best. Our three prompt lines each turned a fifth copy into a reuse of formatRelativeTime: search first, describe the behaviour, name the folder. Tomorrow, try the search line where you know a helper exists. Next time: how an agent decides which commands it may run without asking.

Sources

Written with AI assistance and reviewed by the author.

Top comments (0)