Claude Code relies on fast, reliable file search to do almost everything: finding relevant code, following `@file` mentions, and letting custom agents and skills locate the right files. When search breaks, Claude can suddenly act like it's lost in your own codebase, missing files that clearly exist, returning empty results, or responding much more slowly than usual.
The good news is that file search problems in Claude Code almost always come down to a small set of causes, and most have a direct fix. This guide walks through what's actually happening under the hood, the most common reasons search stops working, and step-by-step solutions for each one including the ripgrep issue that causes the majority of these reports.
Quick Answer
In most cases, "Claude Code search not working" means the bundled `ripgrep` binary that powers Claude Code's Search, Grep, and Glob tools can't run on your system. The fix is to install `ripgrep` yourself and point Claude Code at it with the `USE_BUILTIN_RIPGREP` environment variable. If you're on WSL, the more likely cause is slow disk access across the Windows/Linux filesystem boundary, not a broken tool. And sometimes searching "not working" is really Claude Code looking in the wrong place, the wrong working directory, a gitignored file, or a directory outside the session's scope. Run `/doctor` inside Claude Code first it checks your Search status directly and tells you which situation you're in.
How Search Actually Works in Claude Code
Claude Code doesn't search your files the way a human would, by opening a file browser. It uses a small set of built-in tools:
**Grep** searches file *contents* for patterns. It's built on [ripgrep](https://github.com/BurntSushi/ripgrep) and uses ripgrep's regex syntax rather than POSIX grep syntax, and it respects `.gitignore` by default, so gitignored files are skipped unless Claude passes their path directly.
**Glob** finds files by *name* pattern, such as `**/*.ts`. Unlike Grep, Glob does not respect `.gitignore` by default, so it can surface generated or ignored files alongside tracked ones.
**`@file` mentions** let you pull a specific file or directory straight into the conversation by typing `@` and a path, without waiting for Claude to search for it. This is powered by a separate file-suggestion mechanism, not Grep/Glob directly which is why it can fail even when regular search works, and why it can be overridden with a custom hook (more on that below).
Because Grep and Glob are both built on the ripgrep engine, almost every "search isn't working" symptom the Search tool failing, `@file` not resolving, or a custom skill or subagent failing to locate files traces back to the same underlying component.
Main Causes of Claude Code Search Issues
1. The bundled ripgrep binary can't run on your system
This is by far the most common cause, and it's confirmed directly in Anthropic's own troubleshooting documentation. Claude Code ships with a bundled `ripgrep` binary so it works out of the box on most systems. But on some environments certain Linux distributions, restricted corporate machines, or unusual architectures that bundled binary fails to execute. When it does, the Search tool, `@file` mentions, custom agents, and custom skills all lose their ability to find files, because they all depend on the same binary.
**How to identify it:** Run `claude doctor` in your terminal. If ripgrep isn't working, the Search line won't show `OK (bundled)`.
2. Slow or incomplete search on WSL
If you're running Claude Code inside Windows Subsystem for Linux (WSL) and your project lives on the Windows filesystem (under `/mnt/c/`), search may return fewer results than expected. This isn't a broken tool, it's a disk performance penalty from [reading across the WSL filesystem boundary](https://learn.microsoft.com/en-us/windows/wsl/filesystems). Search still runs and still functions, it's just slower and less complete than on a native filesystem.
**How to identify it:** `Claude doctor` will still show Search as OK in this case, which is the key giveaway that separates this cause from a broken ripgrep binary.
3. Files are excluded by `.gitignore`
Because Grep skips gitignored files by default, a file you expect Claude to find in a content search may simply be excluded from that search. This isn't a bug, it's the default behavior, designed to keep build artifacts and dependencies out of results. Glob doesn't have this restriction by default, so the same file may still turn up in a filename search. You can confirm this directly with `git check-ignore -v path/to/file` if the file is ignored, referencing it explicitly by path with `@` usually still works, since reading a specific file is different from searching for it.
**How to identify it:** Check whether the file or its parent directory is listed in your `.gitignore`. Commonly ignored (and then surprising) paths include `dist/`, `build/`, `.next/`, and `node_modules/`.
4. Confusing Grep's regex syntax with plain-text search
Grep uses ripgrep's regex syntax, not literal string matching. A search for something like `interface{}` in Go code needs to be escaped as `interface\{\}`, because `{}` are regex metacharacters. A filename search like `user.controller.js` is also affected the `.` matches any character, not just a literal period, so it should be escaped as `user\.controller\.js`, or you can ask Claude to search by filename with Glob instead, since Glob matches names directly rather than treating them as regex.
**How to identify it:** Look for special characters parentheses, brackets, braces, `+`, `*`, `.` in the pattern you're searching for.
5. Claude Code is looking in the wrong place entirely
Sometimes search "isn't working" simply because Claude Code's working directory, session scope, or the search term itself doesn't match what you expect:
**Wrong working directory.** Claude Code's working directory is wherever you ran `claude` from. If you launched it from your home folder, a parent directory, or a leftover shell session that had already `cd`'d elsewhere, everything relative resolves from the wrong place. Ask Claude to run `pwd` to check.
**Path outside the session's scope.** By design, Claude Code can only see its working directory and anything explicitly added to it. A file elsewhere on your machine isn't reachable until you run `/add-dir ../other-package`, or configure a filesystem MCP server with an allow-list for directories you want available every session.
**The search term doesn't match the code.** "Cannot find it" often really means "searched for the wrong string." Try searching for a UI string, a route path, a config key, an import statement, or a distinctive log message instead of the name you assumed the function or file would have.
**Symlinks, mounts, and containers.** Symlinked directories, network mounts, and container bind mounts can all point search somewhere unexpected. `ls -la` shows symlinks with `->`, and `readlink -f path` resolves the real target. In a container, remember the path inside the container isn't the path outside it.
**Case sensitivity.** macOS is usually case-insensitive; Linux and git are not. A reference like `Utils.ts` that actually lives at `utils.ts` can work locally and then fail elsewhere.
**Very large repositories.** In repos with hundreds of thousands of files, searches can be slow or feel incomplete. Narrowing the request to a specific directory or package (e.g., "search only within `packages/api/src`") both speeds things up and improves relevance.
6. Real bugs reported against Claude Code's search
A few search issues aren't configuration problems at all they're bugs that have been reported against Claude Code itself:
**Search silently for missing text that's clearly in the file.** One reported case on Windows showed the built-in Search tool returning "Found 0 lines" for a word that plain `grep` found instantly in the same file, with no error to indicate anything had gone wrong (GitHub issue #7344, closed as not planned).
**Unicode filenames not matching `@` search.** Typing `@` and searching with non-ASCII characters (for example, Chinese filenames) can fail to surface files that clearly exist, because the file-suggestion search doesn't handle Unicode input reliably (GitHub issue #10879, closed as a duplicate of an existing report).
**`@` file suggestions breaking when `.git` isn't at the repo root.** Developers using git worktrees where the `.git` folder lives outside the working directory have reported that `@file` suggestions stop working well in that setup.
**Non-ASCII paths tripping up file-access tools in Claude integrations more broadly.** A similar symptom has been reported outside Claude Code proper, in the Cursor editor's Claude integration: a file with Cyrillic characters in its path existed, was visible in the file tree, and still returned a "could not find file" error when the model tried to read it suggesting path-encoding edge cases aren't unique to any one tool.
If you hit one of these, the practical workaround is usually the same as for a broken bundled binary: switch to your system's `ripgrep` (Step 2 below), or reference the specific file directly with `@` rather than relying on search to surface it, and avoid non-ASCII characters in filenames where you can.
7. A different problem: Claude.ai Project Knowledge, not Claude Code
It's worth distinguishing Claude Code's file search from a separate, unrelated feature: Project Knowledge in the Claude.ai web interface, where you upload reference documents to a Project. Users have reported cases where an old, deleted file's content keeps surfacing in answers even after it's removed and replaced with an updated version a stale-indexing symptom rather than a search-tool failure. None of the ripgrep-related fixes in this guide apply there, since Project Knowledge doesn't use Claude Code's Grep/Glob/ripgrep pipeline at all; if you're hitting that issue, removing and re-adding the file, or starting a fresh chat outside the affected project, is the more relevant troubleshooting path.
Step-by-Step Solutions
Step 1: Run the built-in diagnostic
Before changing anything, get a clear read on what's actually broken.
claude doctor
Inside a running Claude Code session, you can also run `/doctor` for an automated check of your installation, settings, extensions, and context usage; it will propose fixes it can apply after you confirm. Check the Search line specifically if it doesn't read `OK (bundled)`, the bundled ripgrep binary is the problem, and you should move to Step 2. It's also worth running `claude doctor` again after any environment change: a new machine, a container rebuild, an OS update, or a plugin/hook install since these are the most common points where the bundled binary or a customization stops behaving.
**Expected result:** A clear pass/fail status for Search, along with any other configuration issues.
If search seems to be only one symptom among several high CPU/memory use, hangs, or the terminal freezing a broken customization is also worth ruling out. Restarting with `claude --safe-mode` disables all plugins, MCP servers, and hooks for the session; if search (and everything else) improves, one of your customizations was the cause, not ripgrep itself.
Step 2: Install ripgrep for your platform
If `claude doctor` shows a problem with the bundled binary, install `ripgrep` separately using your platform's package manager.
**macOS**
brew install ripgrep
**Ubuntu/Debian**
sudo apt install ripgrep
**Alpine Linux**
apk add ripgrep
`ripgrep` is in Alpine's community repository. If `apk` reports the package is missing, you'll need to enable that repository first.
**Arch Linux**
pacman -S ripgrep
**Windows**
winget install BurntSushi.ripgrep.MSVC
**Expected result:** `ripgrep` (the `rg` command) is installed and available on your system `PATH`.
Step 3: Tell Claude Code to use your system ripgrep instead of the bundled one
Installing ripgrep alone isn't enough; you also need to tell Claude Code to use it instead of the bundled binary. Set `USE_BUILTIN_RIPGREP` to `0`, either as a shell environment variable or in the `env` block of your `settings.json`:
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}
Environment variables and settings changes take effect on the next session start, so restart Claude Code (or open a new session) after making this change.
**Expected result:** Claude Code stops trying to run its bundled binary and calls your system's `ripgrep` installation instead.
Step 4: Confirm the switch took effect
claude doctor
Check that the Search line now shows the path to your system `ripgrep` binary instead of `OK (bundled)`.
**Expected result:** The search line reflects your system ripgrep path, confirming the override is active.
Step 5: If you're on WSL, address filesystem location instead
If `claude doctor` shows Search as healthy but results still feel incomplete, ripgrep isn't your problem. You have three options, in order of how much effort they take:
1. **Narrow your searches.** Ask Claude to search specific directories or file types instead of the whole project for example, "Search for JWT validation logic in the auth-service package" instead of a broad, unscoped search. This reduces how many files need to be read across the slow filesystem boundary.
2. **Move your project to the Linux filesystem.** If your project currently lives under `/mnt/c/`, moving it under `/home/` (the native Linux filesystem inside WSL) removes the performance penalty entirely.
3. **Run Claude Code natively on Windows** instead of through WSL, if your workflow allows it.
**Expected result:** Faster, more complete search results, since files no longer need to be read across the WSL/Windows filesystem boundary.
Step 6: Check for `.gitignore` exclusions if a specific file is missing
If only one file (or a specific set of files) isn't turning up, rather than search failing broadly, check whether it's excluded by `.gitignore`:
git check-ignore -v path/to/file
Ask Claude to reference the file directly with `@path/to/file`, or pass the exact path so Grep can search it despite the ignore rule.
**Expected result:** The specific file is found once its path is referenced directly or its `.gitignore` exclusion is addressed.
Step 7: Check the working directory and session scope
If nothing above explains it, confirm Claude Code is even looking in the right place:
1. Ask Claude to run `pwd` and compare it to where your project actually lives.
2. If the project (or the file you need) is outside that directory, run `/add-dir ../path/to/other-package` to add it for the session, or set up a filesystem MCP server with an allow-list for a persistent fix.
3. If a file is visible with `ls -la` but Claude still can't find it, check for a symlink (`readlink -f path`) or a case mismatch (`ls -la | grep -i filename`) between what you typed and what's actually on disk.
**Expected result:** Claude Code searches (and can reference) the directory or file that was previously out of scope.
Step 8: Consider a custom `@file` suggestion hook for persistent issues
If `@file` mentions specifically keep failing for example, in a git worktree setup where `.git` isn't at the project root Claude Code lets you override the built-in file-suggestion behavior entirely with a custom hook. In `.claude/settings.json`:
{
"fileSuggestion": {
"type": "command",
"command": "python3 ~/.claude/hooks/hook_file_suggestion.py"
}
}
The hook receives `{"query": "..."}` on stdin and should print matching file paths to stdout, one per line. A minimal version just shells out to ripgrep itself:
#!/usr/bin/env python3
import json, os, subprocess, sys
def main() -> int:
input_data = json.load(sys.stdin)
query = input_data.get("query", "")
if not query:
return 0
project_dir = os.path.abspath(os.environ.get("CLAUDE_PROJECT_DIR", "."))
cmd = f"rg --follow --files | rg -i -F '{query}'"
result = subprocess.run(cmd, shell=True, cwd=project_dir, capture_output=True, text=True)
for line in result.stdout.splitlines()[:15]:
print(line)
return 0
if __name__ == "__main__":
sys.exit(main())
This gives you full control over ordering and which directories get searched — useful if you also want it to search the git repo root even when you're working from a subdirectory, not just the current folder. It's a workaround for edge cases the built-in suggestion engine doesn't handle well, not a replacement for fixing a broken ripgrep binary.
**Expected result:** `@file` mentions resolve reliably even in project layouts (like worktrees) where the built-in suggestion engine struggles.
Common Mistakes to Avoid
**Installing ripgrep but forgetting to set `USE_BUILTIN_RIPGREP=0`.** Having `rg` on your system does nothing by itself Claude Code still defaults to the bundled binary until you explicitly override it.
**Assuming WSL slowness is a bug.** Incomplete WSL results are a known filesystem performance limitation, not a broken installation. Reinstalling Claude Code won't fix it; moving your project or narrowing your search will.
**Writing plain-text patterns into Grep as if it were literal string search.** Unescaped regex metacharacters (like `{`, `(`, `.`, `*`) can cause missed matches or outright errors. Escape them, or ask Claude to do it for you.
**Not checking `claude doctor` first.** Guessing at the cause and trying random fixes wastes time. The diagnostic command distinguishes a broken ripgrep binary from a WSL slowness issue in seconds.
**Assuming "not found" always means a search bug.** Nine times out of ten, a file Claude Code "can't find" is really a working-directory, session-scope, or gitignore issue rather than anything wrong with search itself check those before assuming ripgrep is broken.
**Confusing Claude Code's file search with Claude.ai's Project Knowledge.** They're different systems with different failure modes; a ripgrep fix won't help a stale-file issue in a web Project, and vice versa.
Best Practices to Prevent Future Search Issues
**Run `claude doctor` after any environment change** a new machine, a container rebuild, or an OS update since these are the most common points where the bundled ripgrep binary stops working.
**Keep projects on a native filesystem** relative to where Claude Code runs, especially on WSL, to avoid cross-filesystem read penalties.
**Scope large searches deliberately** in big codebases mentioning a specific directory, package, or file type rather than relying on an unscoped search across the entire repository. This helps both search speed and result relevance regardless of platform.
**Use `@file` references for files you already know you need**, rather than relying on search to rediscover them each time, since `@` mentions pull content directly without depending on the search tools at all.
**Document your project's layout in `CLAUDE.md`** (e.g., which folders hold what, and which are generated and never edited). This gives Claude a map to work from and reduces how often it needs to search blindly in the first place.
Frequently Asked Questions
The most common reasons are a broken bundled ripgrep binary (check with `claude doctor`), the file being excluded by `.gitignore` during a content search, Claude Code's working directory or session scope not covering that path, or — on WSL — a filesystem read limitation that reduces search completeness without breaking it outright.
`Claude doctor` diagnoses issues and, when run as `/doctor` inside a session, can propose fixes it will apply after you confirm. Some issues, like installing a system ripgrep binary, still require a manual step from you.
Glob finds files by name and doesn't filter out gitignored files by default, so it can surface generated or dependency files. Grep, which searches file contents, skips gitignored files by default. This difference is intentional, not a bug.
It stems from how WSL reads across the Windows and Linux filesystem boundary, which is a platform-level constraint documented by Microsoft rather than something specific to Claude Code. Moving your project to the native Linux filesystem or running Claude Code natively on Windows avoids it entirely.
Yes — environment variables and settings changes take effect on the next session start, so restart Claude Code (or open a new session) after setting `USE_BUILTIN_RIPGREP` to `0`.
Grep uses ripgrep's regex syntax, so the `.` in that pattern matches any character, not just a literal period. Escape it as `user\.controller\.js`, or ask Claude to search by filename with Glob instead, since Glob matches names directly rather than treating them as regexes.
Yes — a small number of confirmed reports exist, including Search missing text that plain `grep` finds in the same file on Windows, and `@file` suggestions not matching Unicode filenames. Both have open or closed tracking issues on the Claude Code GitHub repository. If you hit either, switching to your system's ripgrep or referencing the file directly with `@` is the practical workaround.
Use the `/feedback` command inside Claude Code to report it directly to Anthropic, or check the [Claude Code GitHub repository](https://github.com/anthropics/claude-code) for known issues.
Conclusion
Claude Code search not working almost always traces back to one of a few things: a bundled `ripgrep` binary that can't run on your system, a WSL filesystem performance limitation that slows search down without breaking it, or just as often Claude Code simply looking in the wrong working directory, session scope, or `.gitignore`-excluded path. Running `claude doctor` first tells you immediately which situation you're dealing with, so you're not guessing.
From there, the fix is usually mechanical install `ripgrep`, set `USE_BUILTIN_RIPGREP=0`, and confirm the switch with another diagnostic run, or, on WSL, relocate your project or scope your searches more narrowly. For the rarer, harder cases Unicode filenames, git worktrees, or non-standard project layouts a custom `@file` suggestion hook can pick up where the built-in tool struggles.
Once search is confirmed healthy, the Search tool, `@file` mentions, and any custom agents or skills that depend on file discovery should all work as expected again.