Try free

Last updated 13 October 2026

How to exclude node-modules from Claude Code

Dependency folders drain your context window

Every time you run a search in a modern javascript project, you risk flooding your session with thousands of lines of library code. Claude Code uses a context window that fills up as the agent interacts with your files. When the agent uses the Read tool or the Grep tool, it pulls the content of those files into its active memory. In a typical project, the node-modules folder contains millions of characters of code across thousands of files. If the agent accidentally scans this directory while looking for a component or a function, it can consume your entire token limit in a single exchange.

This overflow of information does more than just cost money. It introduces massive amounts of noise into the reasoning process of the agent. When the context is filled with third-party library code, the agent might get confused about where your actual project logic lives. It might suggest changes to a read-only file inside node-modules or try to fix a bug in a dependency instead of your own code. Controlling what the agent can see is the most effective way to keep it fast and accurate. You must treat your folder structure as a boundary that the agent should only cross when explicitly told to do so.

Version control files provide baseline protection

Claude Code is designed to respect your existing version control rules by default. It automatically looks for a .gitignore file in the root of your repository and in subdirectories. If you have already excluded node-modules from your git repository, the agent will typically ignore those files when it uses the Glob tool to list files or the Grep tool to search for strings. This is the first and most important layer of defense. You should verify that your .gitignore is correctly formatted and that the node-modules path is correctly specified for your project structure.

In complex monorepos, you might have multiple node-modules folders at different levels of the tree. The agent checks the local .gitignore in each directory it enters. However, there are times when the agent might use the Bash tool to run standard shell commands like find or ls. These shell commands do not always respect .gitignore rules. If the agent decides to use a raw shell command to explore your project, it might still stumble into your dependencies. Relying on git settings alone is often not enough for a perfectly clean development environment.

Project instructions enforce strict directory boundaries

The most reliable way to keep the agent out of your dependencies is to use a CLAUDE.md file. This file sits in your project root and serves as the primary source of truth for the agent regarding your project rules. You should explicitly list the directories that the agent is allowed to explore and those it must ignore. Write a clear instruction stating that the agent should never use the Read tool on any file within node-modules or build artifact folders like dist or build. You can also tell the agent to focus its searches on specific folders like src or lib.

You can place a CLAUDE.md file in a subdirectory to apply rules to just that part of the tree. If you have a specific module that has its own dependencies or a unique structure, a local CLAUDE.md can provide more granular control. When the agent starts a session or uses the Task tool, it reads these instructions to understand the scope of its work. By defining these boundaries in plain language, you ensure that the agent remains focused on your source code. This practice significantly reduces the number of tokens used per task and keeps the conversation history clean.

Global and local settings refine agent behavior

Beyond project-specific instructions, you can use the .claude/settings.json file to configure how the agent handles permissions and tool usage. This file allows you to define default behaviors for every session in that project. You can also use .claude/settings.local.json for your own overrides that you do not want to check into your version control system. These files give you the ability to fine tune how the agent interacts with your file system. If you want to be extremely safe, you can configure the permissions for the Read tool and the Write tool to always ask for confirmation before accessing certain paths.

If you find yourself working across many different projects, you can use the ~/.claude/settings.json file to set global rules. This is useful for ensuring that node-modules are consistently ignored across every project on your machine. You can also use this global configuration to manage how the agent handles large files. By setting a limit on the maximum file size the agent can read without permission, you prevent it from accidentally loading a massive bundled javascript file from a library. These layers of configuration work together to create a predictable and efficient environment for terminal-based development.

Context management clears accidental library reads

Even with perfect configuration, the agent might occasionally read a large file or a dependency by mistake. When this happens, you will notice the session becoming slower or the agent becoming less responsive to specific prompts. You should use the /compact command immediately. This slash command summarizes the current conversation and clears out the full text of previous file reads and messages from the active context. It keeps the important details while removing the heavy weight of the library code that was accidentally loaded. This is a vital tool for maintaining a long-running session without hitting context limits.

If the session has become completely polluted with irrelevant information from a dependency, you may need to use the /clear command. This command resets the current session in the same folder. It is like starting a new conversation but without the need to navigate back to your directory or re-initialize your environment. While /compact is good for minor cleanup, /clear is for when the agent has lost the thread of the task due to excessive noise. Using these commands regularly helps keep your spend low and your agent's focus high.

Search tools require specific directory constraints

The way you phrase your prompts directly affects how the agent uses its search tools. Instead of giving a general instruction like 'find the user authentication logic', you should provide directory hints. Telling the agent to 'search the src/auth directory for the user logic' encourages it to use the Glob tool and Grep tool with specific path filters. When the agent has a narrow search path, it is much less likely to wander into node-modules. You are essentially providing a map that helps the agent avoid the most resource-intensive parts of your file system.

You can also check the current status of the agent's understanding by using the /status command. This will show you what the agent is currently tracking and its general state. If you see that the agent is attempting to index or search directories that it should not be in, you can interrupt it by pressing the Escape key. Pressing Escape once stops the current tool execution. This allows you to immediately correct the agent's path with a new instruction before it wastes more tokens on a deep dive into your library code. This active supervision is a key skill for efficient terminal development.

Terminal organization improves project focus

Managing multiple parts of a complex project can lead to context confusion. If you are working on a frontend and a backend simultaneously, both will have their own node-modules folders. Using adhdTerminal can help you keep these environments separate. You can run many Claude Code sessions side by side as tiles on a single wall. Each tile can be dedicated to a specific directory or a specific task. By isolating your frontend work in one tile and your backend work in another, you ensure that the agent only has access to the relevant files and dependency rules for that specific context.

This visual organization makes it easy to see if one session is getting bogged down by a large file read. adhdTerminal shows whether a tile is working or waiting for your input. If you see a tile has been 'working' for a long time during a search, it might be stuck in a deep directory like node-modules. You can quickly switch to that tile and intervene. The ability to resume sessions and keep them in the same place after a restart means you do not have to re-configure your exclusion rules every time you start your workday. This persistent setup is a major advantage for developers handling large, dependency-heavy repositories.

Cost monitoring prevents unexpected token expenditure

One of the best ways to verify that your exclusion rules are working is to monitor your usage statistics. The /cost command shows you the financial impact of your current session, while the /usage command gives you a breakdown of the tokens consumed. You should check these numbers after performing major searches or large-scale edits. If a simple search costs significantly more than expected, it is a clear indicator that the agent is reading files it should be ignoring. This data-driven feedback allows you to adjust your CLAUDE.md or .gitignore rules in real-time.

Frequent use of /cost also helps you understand the relative weight of different tools. You might find that the Grep tool is more expensive than the Glob tool when a project is not correctly pruned. By staying aware of these costs, you become a more efficient operator. You can even use adhdTerminal to keep an eye on these numbers as they can be published to the tile headlines. This constant visibility ensures that you never finish a coding session to find an unexpected bill because the agent spent the afternoon reading the source code of your framework's dependencies.

Questions people ask

How can I tell if Claude Code is currently reading node-modules?

You can observe the tool calls in the terminal output while the agent is working. If you see the Read, Grep, or Glob tools being called with paths that start with node-modules, the agent is accessing those files. You can press Escape to stop the process and then update your CLAUDE.md to forbid access to those paths.

What is the fastest way to stop the agent from searching build folders?

The fastest method is to add the build folder names to your .gitignore file, as Claude Code respects these rules by default. For a more explicit block, create a CLAUDE.md file in your project root and add a section titled 'Project Constraints' that lists forbidden directories. This gives the agent a clear instruction to avoid those folders regardless of other settings.

Will /compact remove the rules I set in CLAUDE.md?

No, /compact only summarizes the conversation history and clears the immediate context of previous messages and file contents. It does not affect project-level files like CLAUDE.md or settings.json. The agent will still follow the instructions in those files even after a compaction or a session restart.

Read next

More on claude code basics·All posts