Last updated 13 October 2026
Claude Code stuck on the search command
The search command hangs on large codebases
You type a prompt asking for a specific function across the whole repository. The terminal shows the Grep tool or the Bash tool running. The spinner keeps turning for minutes without any output. This usually happens in projects with thousands of files or deeply nested directories where the tool logic attempts to crawl through every single line of code. It is a common point of frustration when the agent tries to build a mental map of a codebase it does not know yet, especially if the project structure is not immediately clear from the file names.
When Claude Code initiates a search, it often uses the Glob or Grep tools to identify relevant files. If the repository contains large binary files, massive dependency folders, or build artifacts that are not properly excluded, the search process can become bogged down. The agent might be waiting for the operating system to return thousands of lines of text from a minified JavaScript file or a large log file. This causes the interface to appear stuck, even though the underlying process is technically still active but overwhelmed by the volume of data it is trying to parse.
Interrupting a runaway search process
If the search takes more than a few seconds without progress, you should intervene rather than waiting indefinitely. Press the Escape key once to interrupt what the agent is doing. This signals the agent to stop the current tool execution and return to the interactive prompt. It is the most direct way to regain control when a search command goes wrong. Once interrupted, you can provide a more specific prompt to narrow the search area or ask the agent why it thinks the search is taking so long.
In some cases, the agent might get stuck in a loop where it tries the same failing search multiple times. If pressing Escape once does not resolve the issue, press the Escape key twice in rapid succession. This action offers a list of earlier messages in the conversation. You can select a point before the problematic search started and resume from there. This effectively rewinds the state of the session and allows you to steer the agent away from the broad search that caused the hang in the first place.
Configuring ignore rules to skip heavy folders
Claude Code respects your .gitignore file by default, but this is often not enough for complex development environments. If your search is hanging, it is likely that the agent is crawling through directories that do not contain source code. You should verify that your .gitignore file is comprehensive and includes all build directories, temporary files, and heavy dependency folders. If the agent continues to search through files that you want to keep in git but exclude from the agent's view, you can use the settings.json file located in the .claude directory to define more specific tool behaviors.
The agent relies on the file system structure to make decisions about which tools to use. If your project has a flat structure with thousands of files in a single folder, the Glob tool will struggle. Moving files into a more organized directory structure can significantly improve search performance. You can also create a CLAUDE.md file in the root of your project to explicitly list directories that the agent should ignore. While the agent does not automatically exclude everything in CLAUDE.md from a technical bash perspective, providing these instructions helps the agent decide not to run broad Grep commands on those paths.
Using CLAUDE.md to guide the agent
A well-structured CLAUDE.md file acts as a map for the agent. You should include a section that describes the project structure and specifies where the most important logic resides. For example, tell the agent to prioritize searching in the src directory and to avoid the tests directory unless explicitly asked. When the agent starts a session or uses /init, it reads these instructions. This context helps the agent use the Grep and Glob tools with much more precision, reducing the likelihood of a hang.
You can also use CLAUDE.md to define naming conventions for your project. If the agent knows that all database logic is in files ending with .repository.ts, it will use a more specific glob pattern rather than searching every file in the tree. This reduces the workload on the file system and prevents the search tool from stalling. If your project is a monorepo, consider placing a CLAUDE.md file in each major subdirectory to provide localized instructions that apply only to that specific part of the codebase.
Managing long running tasks with adhdTerminal
When you work on several parts of a large system at once, a single search hang can stop your entire workflow. This is where adhdTerminal provides a practical solution for macOS and Windows users. It allows you to run many Claude Code sessions side by side, with each one appearing as a tile on a wall. If a search is taking a long time in one tile, you do not have to wait. You can simply move to another tile and continue working on a different task. Each tile shows whether the session is working, waiting for you, or idle, so you can monitor the progress of a search from the corner of your eye.
The adhdTerminal app also includes a free iPhone app that mirrors your wall of tiles over an encrypted link. If you start a massive search and need to step away from your computer, you can check the status of the task on your phone. You can see the last few exchanges of the conversation and even send the next task once the search completes. This is useful for developers who need to manage long-running background tasks without being tethered to a single terminal window. The app requires a one-time payment of 99 dollars and offers a 7 day free trial to see if it fits your specific workflow.
Switching to plan mode for better oversight
By default, the agent might execute tools automatically depending on your settings. If you find the agent is repeatedly running broad searches that hang, you should change the permission mode. Press Shift+Tab inside a session to cycle through the modes until you reach the plan mode. In this mode, the agent must describe its plan and the specific tools it intends to use before it actually runs them. This gives you the opportunity to see if the agent is about to run a Grep command on the entire root directory.
When you see a plan that involves a broad search, you can intervene by providing a more specific prompt. You might tell the agent to only search in the components folder or to use a more specific search string. This proactive management prevents the hang from happening in the first place. You can also adjust the permissions in your .claude/settings.json file to require manual approval for the Bash tool, which is often used for the most intensive search operations. This ensures you always have the final say on whether a potentially slow command is executed.
Clearing and compacting context to maintain speed
As a session grows longer, the context window fills up with previous search results and file contents. This can slow down the agent's ability to reason about new search tasks. If the agent has already performed several large searches, the sheer volume of data in its memory might make it sluggish. Use the /compact command to summarize the session and free up context space. This keeps the agent focused and ensures that the results of the next Grep or Glob tool are processed efficiently without the overhead of thousands of lines of previous search history.
If the session has become irrecoverably slow or the agent is confused by conflicting search results, use the /clear command. This starts the session over in the same folder while keeping your current project state. It is a clean slate that removes all the accumulated context that might be contributing to performance issues. After clearing, you can use the /resume command if you need to pick up an earlier session that was more stable, or simply start a fresh conversation with a more targeted approach to your search task.
Targeting specific directories with commands
If you know exactly where a piece of code should be, do not let the agent guess. You can use the /add-dir command to explicitly bring a subdirectory into the agent's focus. This signals to the agent that this directory is the primary area of interest for the current task. While the agent can still search elsewhere, it will often prioritize the added directory for its initial Grep and Glob operations. This is much faster than letting it search the entire repository root by default.
You can also use the /terminal-setup command to ensure your environment is optimized for the agent's tools. Sometimes a search hang is caused by terminal configurations that do not play well with how the agent captures output. Ensuring a clean environment helps the agent receive search results in chunks rather than waiting for a massive buffer to fill up. If you are unsure if your installation is healthy, run the claude doctor command from your shell to check for any underlying issues with the tool chain that might be causing performance bottlenecks during search operations.
Questions people ask
How can I tell if Claude Code is actually stuck or just working on a large search?
Check the terminal for an active spinner and look at the tool name being displayed, such as Grep or Bash. You can also run the /status command in a separate tile or terminal window to see the current state of the agent. If there is no disk or CPU activity on your machine for several minutes while the spinner is active, the process is likely hung.
What is the fastest way to stop a search that is taking too long?
Press the Escape key once to send an interrupt signal to the agent. This will stop the current tool from running and return you to the interactive prompt where you can give new instructions. If the agent does not respond to a single Escape press, use Ctrl+C to quit the session entirely and restart with claude --continue.
Can I limit the depth of searches to prevent hangs?
You cannot set a global depth limit in the settings, but you can control it through instructions in your CLAUDE.md file. Tell the agent to never search deeper than two levels in specific directories or to always use specific flags with the Grep tool. Switching to plan mode with Shift+Tab also allows you to manually reject searches that look too broad.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.