Fixing Roo Code's Codebase Index That Returns Stale or Missing Results After a Large Refactor or Branch Switch

The Problem

Roo Code's semantic codebase search has been working well — asking it to find "the function that validates user sessions" reliably surfaces the right file. After a large refactor (renaming a module across dozens of files, moving a directory, or merging two files into one) or after checking out a different git branch, the same kind of query starts behaving strangely: it returns a file path that was deleted days ago, misses a file that obviously contains exactly what was asked for, or ranks a loosely related match above the one that's actually correct. Nothing about the search query changed; what changed is that the index no longer accurately reflects what's actually on disk.

Why It Happens

Codebase indexing is an embeddings-based index built once and then updated incrementally, not recomputed fresh on every search

Roo Code's codebase indexing feature generates vector embeddings for chunks of the project's files and stores them for fast semantic lookup, rather than re-scanning and re-embedding the entire codebase on every single search — recomputing embeddings for the whole project on every query would be far too slow to be usable. This means the index is a snapshot that has to be kept in sync by separately detecting and applying changes, rather than something inherently always current.

A file watcher updates the index incrementally, but a watcher can miss or coalesce changes during a very large, fast batch of file operations

Ordinary day-to-day edits — saving a file, creating a new one — are caught reliably by the file-system watcher that drives incremental index updates. A refactor that renames, moves, or deletes dozens or hundreds of files in a short burst (an IDE-wide rename, a scripted move, a large automated codemod) can produce a volume and pattern of filesystem events that overwhelms or outpaces what the watcher processes cleanly, leaving some of those changes unreflected in the index even though the watcher is technically running.

Switching git branches changes the actual file contents on disk instantly, in a way a file watcher wasn't necessarily designed to treat as a normal edit stream

A git checkout to a different branch can simultaneously change, add, and remove large numbers of files in one atomic filesystem operation, which is a fundamentally different shape of change than the incremental single-file edits the watcher is built around — the index after a branch switch can easily end up as a confused blend of the old branch's embeddings and a partial, incomplete update toward the new branch's actual content.

The Fix

1. Trigger a manual reindex immediately after any large refactor or branch switch, rather than trusting the incremental watcher to have caught everything

Command Palette -> "Roo Code: Rebuild Codebase Index"
(or, from the Roo Code settings panel: Codebase Indexing -> Rebuild Index)

Treating a full reindex as a deliberate step after any change large enough to plausibly overwhelm the watcher — rather than assuming the index silently kept up — closes the gap directly: a fresh full build re-embeds the project's actual current state from scratch, with no dependency on whether every individual filesystem event during the refactor was caught correctly.

2. Check the indexing status panel for an error or a stuck "in progress" state before concluding the index is simply out of date

Roo Code settings -> Codebase Indexing -> check status: Indexed / Indexing / Error
A stuck "Indexing..." state after several minutes with no file-count change
usually means the indexing process itself needs restarting, not just re-triggering.

An index that's stale because an update is still legitimately in progress on a large project looks identical from the search results alone to one that's stale because indexing silently failed or hung — checking the actual status before assuming a simple staleness problem saves time that would otherwise go into repeatedly re-running searches against an index that was never going to finish updating on its own.

3. For a workflow that branch-switches frequently, reindex as a deliberate step of the switch itself rather than an afterthought triggered by a bad search result

# A simple wrapper, aliased or added to a project script, making
# the reindex trigger part of the branch-switch habit rather than
# something remembered only after search results look wrong:
git checkout "$1" && echo "Now run: Roo Code: Rebuild Codebase Index"

Building the reindex step into the branch-switch routine itself — even just as a reminder — turns an easy-to-forget manual step into part of the normal workflow, which matters most for exactly the projects and workflows where branch switching happens often enough that stale-index search results would otherwise become a recurring, low-grade annoyance.

4. For very large monorepos, scope indexing to the actively worked-on subdirectory rather than the entire repository, reducing both the staleness window and the rebuild cost

// .roo/settings or equivalent codebase indexing scope configuration
{
  "codebaseIndex": {
    "includePaths": ["packages/app", "packages/shared-ui"]
  }
}

A smaller indexed scope means both less content a large refactor or branch switch can desynchronize in the first place, and a dramatically faster full reindex when one is needed — for a monorepo where most work happens in one or two packages, indexing only those rather than every package in the repo reduces how often staleness becomes noticeable at all.

Why This Works

A stale search result is never a sign the semantic search itself is unreliable — it's a sign the embeddings index and the actual filesystem have drifted apart, which is an entirely expected side effect of an index that updates incrementally rather than being recomputed on every query. Manually rebuilding after large changes, verifying the indexing status directly rather than inferring it from search quality, folding reindexing into a branch-switch habit, and scoping the index to what's actually being worked on all address that same drift directly, rather than trying to make incremental updates somehow catch every edge case.

Conclusion

Codebase search returning stale or missing results after a large refactor or branch switch is the embeddings index falling behind the actual filesystem, not a search quality problem. Manually rebuilding the index after large changes, checking indexing status directly, treating reindexing as a normal part of branch switching, and scoping a large monorepo's index to the active working set together keep semantic search results trustworthy even through changes big enough to outpace incremental updates.