Try free

Last updated 13 October 2026

Why Claude Code is slow to index files

Large file trees cause terminal lag

When you type the command claude in a large project folder, you might notice a significant delay before the interactive prompt appears. This lag happens because the agent must perform an initial scan of your directory structure to understand the environment. If your repository contains thousands of files, the agent spends time mapping out the file system. This process is necessary for tools like Glob and Grep to function correctly later, but it can feel like the terminal has frozen during the startup phase. Developers working on monorepos or legacy projects with deep nesting often encounter this performance wall immediately.

The startup delay is usually tied to the number of files the agent needs to track in its internal index. If the project contains large assets, deep dependency folders, or generated build artifacts, the agent tries to account for them. This creates a heavy workload for the underlying file system watchers. You can check if your installation is performing as expected by running the command claude doctor. This command verifies the environment and ensures the agent has the necessary permissions to operate. If the doctor command reports no issues, the slowness is likely a direct result of the volume of data in your current working directory.

Exclusion rules in the gitignore file

Claude Code respects the rules defined in your .gitignore file. This is the most effective way to speed up the indexing process. If you have not ignored your node-modules folder, your build directories, or your log files, the agent will attempt to read and index every single one of those files. This unnecessary data bloat slows down the Read and Glob tools. By ensuring your .gitignore is strictly configured, you prevent the agent from wandering into folders that do not contain relevant source code. This reduces the total file count the agent must manage.

If you have a folder that you want git to track but you want the agent to ignore, you must still find a way to exclude it from the agent's view. The agent relies on these ignore rules to prune its search space. Every file that is not ignored is a potential candidate for the Grep tool to search through. When the search space is narrow, the agent returns answers much faster. Review your project root for any large data files or hidden directories that do not need to be part of the coding conversation. Adding these to the ignore list will provide an immediate boost to the responsiveness of the command line interface.

Project instructions in the root directory

The agent looks for a file named CLAUDE.md in the root of your repository. This file is intended to hold project instructions and context. You can use this file to guide the agent away from slow or irrelevant parts of your project. If you tell the agent specifically where the important source code lives, it will spend less time guessing and searching. For example, you can use CLAUDE.md to define the primary build commands and the location of the main logic. This helps the agent use the Read and Write tools more efficiently because it has a roadmap of the project structure.

You can also have a CLAUDE.md file in a subdirectory if you are working on a specific module. This allows the agent to focus its attention on that specific part of the tree. If you find yourself working across many different projects, you can even place a CLAUDE.md file in your home directory at ~/.claude/CLAUDE.md. This global file applies to every session and can include general preferences that help the agent operate faster. By providing clear guidance on the project layout, you reduce the number of exploratory Glob calls the agent needs to make, which saves both time and processing power.

Context management with session commands

As a session progresses, the conversation history and the contents of the files the agent has read fill up the context window. A full context window makes the agent slower to process new prompts because it has more information to weigh before responding. You can manage this by using the /compact command inside a session. This command summarizes the conversation so far and clears out the unnecessary details. This frees up space and often restores the speed of the agent. It is a good practice to use /compact after a long debugging session or after a major task is completed.

If the session becomes too cluttered and the /compact command is not enough, you can use /clear to start over in the same folder. This wipes the current context but keeps you in the same working environment. Keeping your sessions lean is a key part of maintaining high performance. You can monitor the cost and resource usage of your current session with the /cost and /usage commands. These provide insight into how much data is being processed. If you see the costs rising quickly, it is a sign that your context is becoming too large and a compaction or a restart is necessary.

Permission modes and tool execution

The speed of the agent is also affected by how often it has to wait for your approval. By default, the agent may ask for permission before using certain tools or editing files. You can change the permission mode by pressing Shift+Tab inside a session. The available modes are default, acceptEdits, plan, and bypassPermissions. If you are in a trusted environment and want the agent to move as fast as possible, using a more permissive mode reduces the back-and-forth interruptions. This allows the agent to execute a sequence of Bash or Edit commands without stopping for manual confirmation at every step.

You can also fine-tune these permissions in the .claude/settings.json file within your project. Under the permissions key, you can allow or deny specific tools. If the agent knows it has pre-approved access to certain tools, it can plan its tasks more effectively. However, you should use these settings carefully. While bypassPermissions is the fastest mode, it gives the agent full control over your terminal. Balancing speed and safety is part of the configuration process. If the agent seems slow because it is constantly waiting for you, check your current mode in the status bar and adjust it to fit your current task.

Visualizing multiple project sessions

If you are working on a very large repository where indexing or complex tasks take several minutes, the wait time can break your focus. This is a common issue for developers with ADHD or those who jump between different tasks frequently. One way to handle this is by using adhdTerminal. This is a native app for macOS and Windows that lets you run many Claude Code sessions side by side. Each session is a tile on a wall, and you can see at a glance if a session is working, waiting for you, or idle. This allows you to start a heavy indexing task in one tile and move to another project in a different tile without losing track of your progress.

The app shows the last exchanges of each conversation and can display headlines or numbers that your project publishes. If a session is taking a long time to index or run a complex task, the tile will show it is working. This visual feedback helps you manage your time because you do not have to keep checking back on a hidden terminal window. You can also use a free iPhone app to mirror this wall over an encrypted link. This lets you monitor a long-running indexing process or a complex build from a distance. By running sessions in parallel, you can stay productive even when one specific session is slowed down by a large file tree.

Local settings and user overrides

Configuration plays a major role in how the agent initializes. Settings are stored in several locations, including .claude/settings.json in your project and ~/.claude/settings.json for your user profile. If you have specific hardware or network constraints that make indexing slow, you might need to adjust your local configuration. You can also create a .claude/settings.local.json file for overrides that you do not want to track in your git repository. This is useful for machine-specific settings that might improve performance on your local dev box.

The /config command allows you to view and modify these settings from within the session. If you find that the agent is frequently trying to use tools that are slow in your environment, you can adjust the tool-specific settings here. For example, if the WebSearch tool is not needed for your current project, disabling it might prevent the agent from attempting slow external lookups. Customizing your environment ensures that the agent only uses the resources it absolutely needs. This keeps the execution loop as tight as possible and prevents the agent from wasting time on tasks that do not contribute to the final goal.

Resuming existing sessions for speed

Starting a fresh session with the claude command is often the slowest way to work because the agent has to rebuild its context. If you have recently worked in a folder, you should use the claude --continue command, or -c for short. This carries on the most recent session in that folder, which is much faster because the agent can pick up where it left off. This avoids the overhead of a completely new initialization. If you want to go back to a specific session from earlier in the day, use the claude --resume command, or -r, to see a list of previous sessions to pick from.

Inside a session, the /resume command can also be used to switch between different tasks. Using these commands effectively reduces the number of times you have to wait for a full project scan. The agent is designed to remember the state of your project across these resumes. This means the work it did to understand your file tree is not lost when you quit the terminal with Ctrl+C. By staying within the same session history, you ensure that the agent remains fast and responsive throughout your workday. Always prefer resuming an existing session over starting a new one unless you specifically want to clear the previous context.

Questions people ask

How can I stop the agent if it gets stuck in a long file scan?

You can press the Escape key once to interrupt what the agent is doing. If you need to exit the session entirely, use Ctrl+C. Pressing Escape twice will also offer you the option to go back to earlier messages in the history.

Does Claude Code index binary files like images or compiled binaries?

The agent generally avoids binary files and focuses on text-based source code. However, if these files are not in your .gitignore, the agent may still spend time listing them during a Glob or Grep operation. Excluding them in your ignore file is the best way to ensure they do not slow down the indexing process.

What should I do if the indexing is consistently slow even on small projects?

Run the claude doctor command to check for any installation or environment issues. It is also a good idea to run claude update to ensure you are using the latest version of the tool. If the problem persists, check your ~/.claude/settings.json to see if any global settings are interfering with the startup process.

Read next

More on when it goes wrong·All posts