Codebase search

Codebase search is how Claude Code locates code: it runs a plain-text search and reads files on demand, with no prebuilt index of your project.

Last updated: 29 Sep, 2026 · Claude Code

In the video the project has no CLAUDE.md yet, so Claude Code knows nothing about it. Asked to say what the project is all about, it lists the directories, reads the README and the markdown files, and asks permission to run a command to look inside the folders. The video approves it. The command was written for PowerShell and fails in bash with exit code 127, so Claude reads the notebooks directly instead, which is the loop checking its result and trying another way. Then it answers: a hands-on tutorial repository for the new LangChain APIs, create_agent and the middleware system.

There is no index anywhere. It finds code the way you would, with search and reading, and that explains a surprising amount of its behaviour.

The capture in the agent-loop lesson is the evidence. The first thing it did was grep. It used a plain text search, run in your shell against your files when needed, rather than an embedding index or a symbol database.

grep -r "short" /tmp/linkshort --include="*.py" | head -20

Then it read the one file that looked right. Two steps, and it had what it needed.

What follows from it

• Nothing is stale. There is no index to rebuild, so it always sees the file as it is on disk right now.
• Nothing was uploaded. Only the parts it read go to the model, not your repository.
• Names matter. A function called next_code is findable. One called helper2 is not.
• Big repositories cost more. Searching is cheap, reading is not, and reading is what fills the context window.

The last point is the one that turns into a bill. A question that makes it read fifteen files costs more than one that makes it read two, and the large-codebases lesson is about working in a repository too large to read.

Helping it find things

You can point it directly at a file, which skips the searching entirely.

claude -p "explain next_code in shorten.py"

Inside a session you can do the same with @ followed by a path, and it will read that file before answering. It is the cheapest way to make an answer better: tell it where to look when you already know.

Related

• Previous: Agent loop
• Next: Permissions
• Reference: Claude Code docs