Feature request: Add codebase indexing

Try this:

GitHub Issue Response

You've hit on a crucial aspect of working effectively with code agents: managing token consumption, especially during intensive tasks like codebase analysis and review. While a built-in persistent indexing feature is an interesting idea for the future, there's a powerful existing mechanism in Claude Code designed to solve this exact problem: sub-agents.

The key benefit is that each sub-agent operates in its own isolated context window. This means you can delegate the "heavy lifting" of searching and reading through files to a specialized agent without polluting your main conversation's context and burning tokens. The main agent only receives the final, concise result.

Recommendation: Create a code-searcher Sub-agent

I'd recommend creating a dedicated sub-agent for this workflow. You can think of this as building your own specialized "indexer" or "reviewer" for your project.

Here's how you can set one up using the /agents command:

1. Run /agents in your Claude Code terminal.
2. Select "Create New Agent".
3. Define the agent with a configuration like this:

```yaml
---
name: code-searcher
description: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Use this for any task that involves locating specific functions, classes, or logic.
tools: Read, Grep, Glob, Ls
---
You are an expert code searcher and analyst. Your goal is to answer questions about the codebase as efficiently as possible.

1. Understand the User's Goal: Clarify what the user is looking for.
2. Plan Your Search: Use Glob and Grep to locate relevant files and code snippets.
3. Read and Analyze: Read only the most relevant files to understand the context.
4. Synthesize and Summarize: Provide a concise answer. Do not output the full contents of large files unless specifically asked. Instead, provide file paths, function names, and a brief summary of the relevant logic.

```

How to Use Your New Agent

Once created, you can delegate tasks to it explicitly:

> Use the code-searcher agent to find all functions related to user authentication and list the files where they are defined.

Claude Code will then spin up the code-searcher in a separate context. That agent will perform all the necessary Grep, Glob, and Read operations. The tokens used for reading those files will be contained within the sub-agent's context.

Finally, the sub-agent will return only the summarized result (e.g., a list of files and function names) to your main conversation, keeping your primary context clean and your token usage low.

This approach gives you a powerful, reusable pattern for any task that requires deep, but temporary, context. You can create other agents for different workflows, like a test-runner or a security-reviewer.

You can learn more in the official documentation:

• Sub Agents Documentation
• Common Workflows: Use specialized sub agents

Let us know how this works for you

Does a code search plugin help? https://github.com/zilliztech/claude-context

I'd recommend creating a dedicated sub-agent for this workflow. You can think of this as building your own specialized "indexer" or "reviewer" for your project.

That keeps your context clean, but doesn't do anything to reduce token consumption - if anything it increases it, as that new agent has even less context then your current chat does.

The benefit of true indexing like cursor (or even Gemini Chat Assist!) is when a user asks Claude "Can you help me write a new back-end migration", the codebase is queried based on that question and returns relevant code snippets + the original prompt to Claude in one shot. That way Claude doesn't have to do 10 iterations of "Hmm, let me see, ls -a, rg, oops, looks like I'm in the wrong dir, cd && rg <**>....." etc.

And in a system like cursors where the index is in the cloud, the other benefit is that there's way more compute to query it with. If your codebase is in a local Elasticsearch docker image that's limited to half a gig of ram, you won't be able to query it as fast or accurately compared to some beefy kb server.

A plugin or mcp is a decent solution, but then that's just one more service running in the background, more mcp tools clogging up the context, etc.

that would be a great addition. there are mcps that do that, but native is aways better I guess

@williamhrs what mcps do you know for indexing?

I just found:
https://github.com/zilliztech/claude-context
https://github.com/bartolli/codanna

yeah, specific for code there isn't many.. (just found this new ones below)

https://github.com/johnhuang316/code-index-mcp
https://github.com/casualjim/breeze
https://github.com/qodo-ai/open-aware

I wanted to use claude context, but didn't want to use the proprietary vector, so doesn't work well for me...

but kilo code, roo, etc have it native and seens to work nice

I'm hitting serious code search performance issues with Claude Code on large repositories. When compared with GitHub Copilot in VSCode or Cursor, Claude Code easily takes between 2x and 2.5x longer on average to analyze the code and produce the response for the exact same question. I'm talking 1 minute versus over 2 minutes here.

Both GitHub Copilot and Cursor have built-in code search capabilities that are really good, why is Claude Code still doing simple grepping of files? GitHub Copilot has remote workspace indexing for GitHub repositories - it doesn't even have to perform local indexing, saving a lot of local compute resources. As for Cursor, I didn't do anything special, it just worked out of the box with search capabilities similar to GitHub Copilot.

Here's a side-by-side video showing how major the difference in performance is between GitHub Copilot and Claude Code: https://bsky.app/profile/awakecoding.com/post/3m5f2bvvbl227

Even if cost wasn't an issue, performance certainly is.

Perhaps for this reason, they haven't added it yet?
https://cline.bot/blog/why-cline-doesnt-index-your-codebase-and-why-thats-a-good-thing

@apatel369 there are definitely a lot of ways code indexing can fail to perform, but what I see is GitHub Copilot doing an excellent job at it, while Claude Code remains in the stone age with basic grepping and background agents that take twice longer to complete. Why isn't Anthropic putting effort where the competition is obviously succeeding?
https://github.blog/news-insights/product-news/copilot-new-embedding-model-vs-code/

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

This feature request is still relevant.

"Early versions of Claude Code used RAG + a local vector db, but we found pretty quickly that agentic search generally works better. It is also simpler and doesn’t have the same issues around security, privacy, staleness, and reliability."
from Claude code creator Boris

https://x.com/bcherny/status/2017824286489383315?s=20

I would like to use Claude Code in Cursor because I prefer their limits policy, but when I tried to use Claude Code, the results disappointed me, the Antropic models in Cursor seem to work better, perhaps this is due to the indexing of the codebase or the system's promptness is better, I don't know

Interesting that Boris mentioned they tried RAG + vector DB early on but moved to agentic search. That makes sense for general use, but for larger codebases the agentic grep approach has real limits: it burns context window pulling in irrelevant files, and it completely misses conceptual matches where the naming doesn't align with what you're searching for.

I actually built a plugin that fills this gap. It indexes your codebase with embeddings and does hybrid search: semantic similarity combined with BM25 keyword matching and identifier boosting. So when you search "authentication flow" it finds login_handler, verify_token, session_middleware even though none of those strings match literally.

The key insight was that you don't need to replace agentic search, you just need to give the agent better search tools. Claude Code's plugin system makes this straightforward: it hooks into lifecycle events so the index auto updates as you edit files.

Runs fully local with Ollama, stores everything in SQLite, no API keys needed for the default setup. In my testing it cuts context pollution by about 60% on codebases over 50k lines.

https://github.com/sagarmk/beacon-plugin

A hook-based approach can provide lightweight codebase indexing by building a project map on session start:

INDEX_FILE=".claude/project-index.md"
INDEX_AGE=3600  # Rebuild if older than 1 hour
if [ -f "$INDEX_FILE" ]; then
    AGE=$(( $(date +%s) - $(stat -c %Y "$INDEX_FILE" 2>/dev/null || echo 0) ))
    [ $AGE -lt $INDEX_AGE ] && exit 0
fi
echo "Building project index..." >&2
cat > "$INDEX_FILE" << HEADER
HEADER
find . -maxdepth 3 -type f \( -name '*.ts' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' -o -name '*.rb' \) | head -50 | sort >> "$INDEX_FILE"
echo -e "\n## Key files" >> "$INDEX_FILE"
for f in src/index.ts src/main.py main.go cmd/main.go src/main.rs; do
    [ -f "$f" ] && echo "- $f" >> "$INDEX_FILE"
done
for f in package.json pyproject.toml Cargo.toml go.mod Makefile docker-compose.yml; do
    [ -f "$f" ] && echo "- $f" >> "$INDEX_FILE"
done
echo -e "\n## Exports/API" >> "$INDEX_FILE"
grep -rn 'export\s\+\(default\|function\|class\|const\)\|^def \|^class \|^func ' src/ 2>/dev/null | head -30 >> "$INDEX_FILE"
echo "Index built: $INDEX_FILE" >&2
exit 0

Inject the index into context:

MARKER="/tmp/cc-index-loaded-$$"
[ -f "$MARKER" ] && exit 0
touch "$MARKER"
INDEX=".claude/project-index.md"
[ -f "$INDEX" ] || exit 0
jq -n --arg idx "$(cat "$INDEX")" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":$idx}}'
exit 0

This gives Claude a map of your codebase structure and key exports on every session start, reducing the need to re-scan the same files. The index rebuilds automatically when stale.