Try free

Last updated 13 October 2026

Fix slow grep in Claude Code

Large repositories slow down initial searches

Claude Code relies on the Grep tool to find patterns across your project. When you ask a query that requires scanning thousands of files, the agent might hang or time out. This happens because the Grep tool must iterate through every file that is not explicitly ignored. If your project contains large build artifacts, dependency folders, or data sets, the search operation consumes significant time and tokens. The agent might try to read too many files at once, leading to a bottleneck in the interactive session.

You can observe this behavior when the agent starts a task and spends several minutes on a single search command. It often shows a progress indicator for the Grep tool. If this process feels sluggish, the tool is likely traversing directories that do not contain source code. Claude Code respects the .gitignore file by default, but it cannot know which parts of your tracked code are irrelevant for a specific search unless you provide more constraints. Identifying the specific folders that cause these delays is the first step toward a faster workflow.

Proper gitignore configuration reduces the search space

The most effective way to speed up the Grep tool is to ensure your .gitignore file is comprehensive. Claude Code uses this file to prune the tree before it even attempts a search. If you have large log files, temporary build outputs, or vendor directories that are not ignored, the agent will scan them every time it performs a project-wide search. Open your .gitignore in the root of your repo and verify that all non-essential directories are listed. This includes common folders like node-modules, target, bin, or dist.

If you have files that you want to keep in the repository but do not want Claude Code to search, you can still use the .gitignore file to exclude them. The agent will follow these rules strictly. By narrowing the scope of the search to only the active source code, you reduce the time the Grep tool spends on disk I/O. This change alone often resolves most performance issues related to slow searches or timeouts. It also prevents the agent from accidentally reading irrelevant context that could confuse its reasoning process.

Use CLAUDE.md to provide architectural maps

Claude Code looks for a file named CLAUDE.md in the root directory of your project to understand how to interact with your code. You can use this file to guide the agent toward the most important parts of your codebase. Instead of letting the agent search the entire tree for a specific component, describe the directory structure in CLAUDE.md. Tell the agent where the primary logic, UI components, and API handlers live. This context helps the agent make more targeted use of the Glob and Grep tools.

A well-structured CLAUDE.md acts as a map for the agent. When you provide clear instructions on where to find specific types of code, the agent is less likely to trigger a global grep. It will instead use the Glob tool to list files in specific subdirectories first. This targeted approach is significantly faster than scanning every file for a string. You can even create multiple CLAUDE.md files in subdirectories to provide localized instructions for different modules. This strategy keeps the agent focused on the relevant parts of the tree and prevents unnecessary search overhead.

Focused sessions prevent context bloat

Performance degrades as the session context window fills up with search results and file contents. Every time the agent reads a file or gets grep output, that data stays in the conversation history. If you have been working in one session for a long time, the overhead of processing the existing context can slow down new search operations. You can use the /compact command to summarize the session and free up space. This removes the granular details of previous searches while keeping the high-level progress, which helps the agent stay responsive.

If the search remains slow even after compacting, consider starting a fresh session with the /clear command. This resets the conversation in the current folder, allowing the agent to start with a clean slate. You can also use the claude -p command to run a single prompt if you only need a quick answer without the full interactive environment. Keeping your sessions short and focused on specific tasks prevents the performance decay that occurs in long, complex conversations. If you need to return to an older discussion, you can use claude --resume to see a list of previous sessions.

Tile management helps parallelize complex tasks

When you are dealing with a massive project, you might need to search across different modules simultaneously without waiting for one grep to finish. This is where adhdTerminal becomes a useful addition to your workflow. The app allows you to run many Claude Code sessions side by side as tiles on a wall. You can dedicate one tile to searching the frontend code and another to the backend. Each tile shows whether it is working, waiting, or idle, so you can manage multiple long-running search tasks at once.

By splitting your work across multiple tiles, you avoid the bottleneck of a single linear session. If a search in one module is taking too long, you can continue working in another tile. Each tile can have its own name and color, making it easy to track which part of the project you are querying. This setup is particularly helpful when you need to compare search results from different branches or versions of the codebase without constantly switching directories or clearing your history manually.

Monitor tool usage and costs

The /cost and /usage commands provide insight into how much data the agent is processing during its searches. If you notice that a single search is consuming a large number of tokens, it is a sign that the Grep tool is returning too much information. This often happens if the search term is too generic. When the agent receives a massive amount of text from a grep operation, it must process all of it, which slows down the response time. You can adjust tool behavior in the .claude/settings.json file to manage how the agent handles these operations.

You can also check the health of your installation with the /doctor command or the claude doctor command from your shell. This ensures that the environment is set up correctly and that there are no underlying system issues affecting the performance of the tools. If the agent is consistently slow across different projects, there might be a configuration issue or a network bottleneck. Using these built-in diagnostic tools helps rule out platform-level problems before you spend time optimizing your repository structure.

Refine search queries for better tool performance

The way you phrase your request to Claude Code directly influences how it uses the Grep tool. If you ask the agent to find something everywhere, it will likely perform a global search. Instead, try to be as specific as possible about the files you are interested in. Mention specific file extensions or directory names in your prompt. This encourages the agent to use the Glob tool first to narrow down the file list before it starts searching for text patterns.

If a search is taking too long, you can press the Escape key to interrupt the agent. This stops the current tool execution and allows you to provide more specific instructions. For example, if you see the agent searching the entire project for a common string like error, you can interrupt it and tell it to only search in the logs or specific source folders. Learning to guide the agent in real-time prevents wasted time and compute resources on inefficient search patterns. You can also press Escape twice to go back to earlier messages if a search went down the wrong path.

Use subagents for distributed searching

For very large codebases, you can define subagents in the .claude/agents directory to handle specific search tasks. A subagent can be configured with instructions that limit its scope to a particular part of the project. When you invoke a subagent using the /agents command, it operates independently of the main session. This allows you to delegate complex searching or indexing tasks to a specialized agent while you continue with other work in the primary interface.

Subagents follow the instructions provided in their markdown files. You can use these files to set strict boundaries on which tools the subagent should use and which directories it should focus on. This modular approach is highly effective for large teams or complex projects where a single agent might get overwhelmed. By isolating search-heavy tasks into subagents, you keep the main session fast and responsive, ensuring that the Grep tool only runs on relevant subsets of the code.

Mobile monitoring for long operations

Sometimes a project-wide search or a complex refactoring task simply takes time, even with optimization. If you are using adhdTerminal, you can use the free iPhone app to monitor the progress of these long-running tasks away from your desk. The app mirrors your wall of tiles over an end-to-end encrypted link. You can see at a glance if a tile has finished its search or if it is waiting for your input. This allows you to stay productive without being tied to your terminal while the Grep tool completes its work.

The mobile app also allows you to send the next task or answer a prompt if the agent needs clarification. This is useful for those moments when a search returns unexpected results and the agent asks for further instructions. Instead of coming back to a stalled session, you can keep the process moving from your phone. This integration between the desktop environment and mobile mirroring ensures that large-scale code searches do not become a total block on your productivity.

Questions people ask

Why does Claude Code still search files listed in my .gitignore?

Claude Code generally respects the .gitignore file to exclude unnecessary files from its search tools. However, if you have already added specific files to the session context by reading them, the agent may still reference them. Ensure your .gitignore is in the root of the project and that you have not explicitly asked the agent to bypass its normal search logic.

Can I limit the number of results the Grep tool returns?

You cannot directly set a numerical limit on grep results through a command-line flag in the interactive session. Instead, you should provide specific instructions in your prompt to focus on a certain directory or file type. If the output is too large, use the Escape key to stop the tool and then ask the agent to refine its search criteria.

Does the /compact command affect search speed?

The /compact command helps maintain the overall responsiveness of the session by reducing the size of the conversation history. While it does not change how the Grep tool interacts with your disk, it reduces the amount of context the agent must process after the search is complete. This makes the transition from search results to the final answer much faster in long-running sessions.

Read next

More on when it goes wrong·All posts