Try free

Last updated 13 October 2026

What to do when Claude Code reaches the file limit

Large repositories trigger indexing limits

Claude Code hits a wall when you point it at a massive folder containing tens of thousands of files. You see the agent struggle or return an error about too many files to index. This usually happens because the agent tries to map out the structure of your project to provide better suggestions. If your repository includes large build artifacts, media assets, or deeply nested dependencies, the agent consumes its internal limits before it even looks at your source code. This stops your workflow and prevents the tool from understanding the logic of your application.

The issue is not just about the total size of the disk space used by your project. It is about the number of entries the agent must track in its memory. When you run the claude command in a root folder with many files, the agent attempts to read the directory tree. If this tree is too wide or too deep, the indexing process fails. You need a strategy to filter what the agent sees so it can focus on the files that actually matter for the task at hand.

Respecting your existing git ignore rules

Claude Code looks at your .gitignore file by default. This is your first line of defense against file limit errors. If you have large folders like node-modules or vendor directories that are not in your ignore file, the agent will try to index them. This often leads to the agent hitting the maximum file limit early in the session. Ensure your .gitignore is up to date and covers all generated files, logs, and temporary data.

If you have files that you do not want to track in git but you also want Claude Code to ignore, you can modify your local environment. The agent behaves like a standard developer tool in this regard. It uses the same rules as your shell and your version control system. By tightening these rules, you reduce the workload on the agent. This allows the tool to process your actual source code faster without wasting resources on irrelevant binaries or library internals.

Refining file access through settings

You can control how the agent interacts with your files through the .claude/settings.json file in your project root. This file allows you to define permissions for various tools. If the agent is trying to read too many files during a search, you can adjust the behavior of the Glob and Grep tools. These tools are what the agent uses to find files across the codebase. By restricting their scope or how they are allowed to run, you prevent the agent from triggering a full repository scan that might exceed its limits.

If you want to apply settings across all your projects, you can use the ~/.claude/settings.json file in your home directory. This is useful for global exclusions that apply to every repository you work on. For example, if you always use a specific tool that generates large amounts of metadata, add that metadata folder to your global ignore list. This keeps your sessions clean and prevents the agent from getting stuck in a loop of reading unnecessary files every time you start a new task.

Scoping work with subdirectory instructions

Large projects benefit from localized instructions. You can place a CLAUDE.md file in any subdirectory of your project. While the CLAUDE.md in the root directory provides global context, a file in a subdirectory helps the agent understand specific parts of the tree. When you are working on a specific module, this file tells the agent what is important in that folder. This reduces the need for the agent to explore the entire repository to find relevant context.

Using subdirectory instructions allows you to guide the agent toward the most important files. You can describe the architecture of that specific module and list the most relevant entry points. This focus helps the agent avoid hitting file limits because it does not have to guess which files to read. It follows your map and ignores the noise in other parts of the repository. This is especially effective when your project has a clear separation between frontend, backend, and infrastructure code.

Managing the context window actively

The context window of a session fills up as the agent reads files and performs tasks. If the agent has read too many files, it may reach a point where it can no longer process new information effectively. You can use the /compact command to manage this. This command summarizes the session so far and frees up space in the context window. This is helpful when you have already performed many file reads and want to continue the session without hitting a limit.

If a session becomes too cluttered with file data, you can use the /clear command. This starts the session over in the same folder. It clears the current context while keeping you in the project. This is a good way to reset the file count if you have moved from one task to another. By clearing the history, you give the agent a fresh start. It will only read the files it needs for the new task, which keeps the total number of files in memory low and prevents indexing errors.

Dividing work across multiple sessions

When a project is truly massive, one session might not be enough to handle the entire codebase. You can run multiple Claude Code sessions side by side. This allows you to point one session at your frontend and another at your backend. By doing this, each session only has to index a portion of the files. This is a reliable way to stay under the file limit while still having the agent available for all parts of your project.

Managing multiple sessions in separate terminal windows can be difficult to track. This is where adhdTerminal becomes useful. It runs many Claude Code sessions side by side as tiles on a wall. Each tile shows you exactly what that specific session is doing and which part of the project it is focusing on. This setup lets you divide a large project into manageable chunks without losing sight of the overall progress. You can see which session is waiting for your input and which one is still processing files.

Using targeted commands for navigation

Instead of letting the agent explore the whole project, you can use specific tools to guide it. The agent uses Glob to find files by name and Grep to find text inside files. If you know exactly where the problem is, you can tell the agent to look in a specific folder. You can also use the /add-dir command to explicitly add a directory to the context. This gives you more control over what the agent sees and helps prevent it from scanning the entire repository.

If you find that the agent is still trying to index too much, check your permissions. You can cycle through permission modes using Shift and Tab inside a session. If you set the mode to plan, the agent will describe what it wants to do before it does it. This gives you a chance to see if it is about to read thousands of files. You can then deny the permission or provide a more specific prompt to limit the scope of the search.

Moving between sessions and computers

If you need to step away from your desk but the agent is in the middle of a large task, you can resume your work later. The claude --resume command allows you to pick from a list of earlier sessions. This is helpful if you have hit a file limit and want to try a different approach in the same session later. You do not have to start from scratch every time you encounter a problem with the file limit.

For developers who need to monitor long running tasks on large projects, adhdTerminal offers a free iPhone app. This app mirrors your wall of tiles over an end to end encrypted link. If a session hits a limit or asks for a permission while you are away, you can answer the prompt or send the next task from your phone. This ensures that your large indexing jobs or long coding tasks continue to progress even if you are not at your computer. It makes managing multiple complex sessions across a large codebase much more practical.

Maintaining a clean environment

Regularly cleaning your project environment helps prevent file limit issues. Use the /doctor command to check the health of your Claude Code installation and your current project setup. This command can identify issues with your configuration that might be causing the agent to index more files than necessary. Keeping your tools updated with the claude update command also ensures you have the latest improvements in file handling and memory management.

A clean environment also means managing your shell history and session data. If you have many old sessions that you no longer need, they can clutter your list when you use the resume flag. By keeping your project structure organized and your settings files precise, you create a better environment for the agent. This reduces the chance of encountering file limits and makes the tool more effective at helping you write code in large, complex repositories.

Questions people ask

Can I tell Claude Code to ignore specific files without using .gitignore?

Yes, you can use the .claude/settings.json file in your project or the ~/.claude/settings.json file for global rules. You define these exclusions under the permissions section of the configuration. This is helpful for files that you want to keep in your repository but do not want the agent to read.

What is the difference between /clear and /compact?

The /clear command starts the session over in the same folder by removing all previous conversation and file context. The /compact command summarizes the conversation so far to save space while keeping the essential information. Use /clear when you want a completely fresh start and /compact when you want to continue the same task.

How do I stop the agent if it starts indexing a massive directory by mistake?

Press the Escape key once to interrupt the current action the agent is performing. If you want to go back to an earlier point in the conversation after the interruption, press Escape twice. This allows you to resume from a state before the large indexing task began.

Read next

More on claude code basics·All posts