Try free

Last updated 13 October 2026

Fix Claude Code frozen during file analysis

The terminal stops responding during initial scan

Claude Code often hangs when you first run the claude command in a large project. You see the agent attempt to map the file structure and then the cursor stops moving. This usually happens because the agent is trying to process thousands of files that do not contain useful source code. Large dependency folders, build outputs, and media assets are the primary causes of this behavior. The agent uses the Glob and Grep tools to understand your project, but these tools can struggle with massive file trees.

When the interface freezes, the agent might be waiting for a response from the file system or trying to summarize a binary file it should have ignored. You might see a message about reading files that never completes. This creates a bottleneck where you cannot enter new commands or see the progress of the current task. Understanding why the agent gets stuck is the first step toward creating a smoother workflow in your local development environment. It is a common challenge for developers working on legacy systems or modern web applications with deep dependency trees.

Interrupt the process to regain control

Your first action should be pressing the Escape key once. This sends an interrupt signal to the current tool, such as Read or Glob, and tells the agent to stop what it is doing. If a single press does not work, press the Escape key twice in rapid succession. This opens a menu that allows you to go back to earlier messages in the conversation. It effectively rewinds the state of the session to a point before the freeze occurred. This is a powerful feature that saves you from losing the entire history of your current task.

If the terminal remains completely unresponsive to the Escape key, you must use Ctrl+C to quit the session entirely. This kills the process and returns you to your shell. After a hard exit, you can try to start again using the claude command followed by the --continue flag to carry on the most recent session. However, if the freeze was caused by a specific file or directory, simply restarting might lead to the same result. You need to change the project configuration before the agent attempts to read those files again to ensure the cycle does not repeat.

Update exclusion rules to prevent scanning

Claude Code respects your .gitignore file by default. If the agent is getting stuck in folders like node_modules, vendor, or dist, ensure these are correctly listed in your root .gitignore. Adding these paths prevents the Glob and Grep tools from wasting time on files that are not relevant to your coding tasks. This is the most effective way to reduce the initial indexing load and prevent the agent from freezing during the discovery phase. A clean git configuration results in a much faster experience with the agent.

Sometimes you want to keep files in git but keep them away from the agent. You can create a .claude/settings.json file in your project root to manage more specific behavior. Within this file, you can find a permissions section where you can define how tools interact with your file system. While .gitignore is the primary filter, specific project settings provide a secondary layer of control. Ensuring the agent only sees the source code it needs to edit will significantly improve performance and stability. You can also create a .claude/settings.local.json file for your own overrides that you do not want to track in the main repository.

Direct the agent with project instructions

The CLAUDE.md file is a powerful tool for preventing freezes. Place this file in your project root to provide high-level instructions to the agent. You can explicitly list directories that the agent should never enter or files it should never try to read. When the session starts, the agent reads CLAUDE.md and follows the guidelines you have set. This prevents the agent from making the mistake of scanning a massive data directory or a folder full of compressed logs. It acts as a set of guardrails for the agent's autonomous behavior.

You can also place CLAUDE.md files in subdirectories to apply rules to specific parts of your project tree. For example, if you have a legacy folder that is very large but rarely needs changes, a CLAUDE.md file in that folder can tell the agent to only read it when specifically asked. This granular control keeps the context window clean and prevents the agent from getting lost in irrelevant code. It reduces the likelihood of the agent triggering a long-running search that leads to a frozen interface. Using these files ensures that the agent focuses its energy on the files that actually matter for your current ticket.

Monitor multiple sessions with adhdTerminal

When you work on several large projects at once, managing multiple Claude Code sessions in standard terminal tabs becomes difficult. You might have one session frozen while another is waiting for your input, and it is hard to tell which is which. This is where adhdTerminal provides a better way to work. It runs many Claude Code sessions side by side as tiles on a wall. Each tile has a color, a number, and a name to help you distinguish between different project environments. It shows whether it is working, waiting, done, or idle, and displays the last exchanges of the conversation.

If a session in one tile hangs during a file scan, you can see it immediately because the status indicator stops changing. You can let that tile sit while you continue working in a different tile on the same wall. A free iPhone app mirrors the wall over an end-to-end encrypted link, allowing you to check the status or send the next task while away from your desk. The adhdTerminal app is a native app for macOS and Windows made by MINDBALANCER OU. It costs 99 dollars once with a 7 day free trial and no account required. Tiles reopen in the same place after a restart and resume the same session.

Clear and compact the session context

If a session becomes slow or starts to lag after a long period of use, the context window might be too full. You can use the /compact command to summarize the conversation so far. This frees up space and can resolve performance issues that look like a freeze. If the session is completely broken and you cannot recover it with Escape, use the /clear command after restarting. This starts the session over in the same folder with a fresh slate while maintaining your project settings.

Frequent use of /compact is helpful for long-running tasks. It prevents the agent from having to process too much history every time you send a new prompt. If you find that the agent repeatedly freezes in the middle of a complex task, check the costs with /cost and the token usage with /usage. A very large context can sometimes cause the agent to take a long time to respond, which might be mistaken for a terminal hang. Keeping the session lean is essential for a fast and responsive experience. You should also consider using /memory to see what the agent is currently tracking about your project state.

Verify the installation and environment

Sometimes the freeze is not about your files but about the Claude Code installation itself. Run the claude doctor command to check for common issues with your environment. This command verifies that your credentials are valid and that the agent can reach the necessary services. If the doctor command reports errors, follow the suggested fixes to restore functionality. You should also run claude update regularly to ensure you have the latest bug fixes and performance improvements. Keeping the tool updated is the best way to avoid known issues with file indexing.

The terminal environment itself can also cause issues. If you are using a non-standard shell or a complex terminal multiplexer, try running Claude Code in a basic terminal window to see if the problem persists. Use the /terminal-setup command inside a session to optimize how the agent interacts with your console. This can fix display glitches that look like the agent has stopped responding when it is actually just failing to render the output correctly. Verifying your terminal settings ensures that the interactive elements of the interface work as expected.

Manage subagents and external tools

Claude Code can launch subagents to handle specific parts of a task. These subagents use instructions found in the .claude/agents folder. If a subagent gets stuck during a complex file analysis, it can cause the main session to appear frozen. You can use the /agents command to see what subagents are currently active and what they are doing. If a subagent is not responding, you may need to interrupt the main process to regain control and investigate the subagent instructions.

Similarly, MCP servers configured in .mcp.json can sometimes hang. If the agent is waiting for a response from an external tool through an MCP server, the whole interface will wait. Use the /mcp command to check the status of your connected servers and manage their configuration. If one is failing, you might need to restart it or check its specific logs for errors. Ensuring that all external dependencies and subagents are running correctly is vital for preventing the main Claude Code interface from locking up during a task.

Questions people ask

Can I exclude files without using .gitignore?

You can use a CLAUDE.md file to give the agent specific instructions on which directories to ignore. You can also define tool permissions in .claude/settings.json to restrict the Read and Glob tools. This allows you to keep files in your repository while preventing the agent from indexing them.

What should I do if Ctrl+C does not close the session?

If the terminal is completely locked, you may need to use your operating system task manager to kill the process. Search for a process named 'claude' and terminate it manually. After doing this, run the claude doctor command to ensure your local state was not corrupted by the hard exit.

Why does the agent try to read binary files?

The agent uses tools like Glob to find relevant files, and sometimes it identifies a binary file as a potential match for your request. If the file extension is not recognized, the agent might attempt to read it as text, which can cause a hang. You can prevent this by adding common binary extensions to your .gitignore or specifying file types in your CLAUDE.md instructions.

Read next

More on when it goes wrong·All posts