Try free

Last updated 13 October 2026

How to tell Claude Code to ignore specific file extensions

Controlling noise in your development environment

Claude Code reads your project files to understand context and provide accurate suggestions. If your project contains large binary files, minified JavaScript, or extensive build artifacts, the agent might waste time processing data that does not help with your current task. This leads to higher costs and fills the context window much faster than necessary. You need a way to tell the agent to stay away from specific file types like .log, .pdf, or .min.js files to keep your sessions efficient and focused.

When the agent reads a file that is too large or irrelevant, it adds unnecessary tokens to the conversation. This can trigger the need for the /compact command sooner than you would like, which forces the agent to summarize the conversation and potentially lose fine-grained details. By filtering out specific extensions, you ensure that the agent only sees the source code that matters. This makes the agent more efficient and reduces the chance of it making suggestions based on outdated build files or temporary logs that should have been ignored.

Relying on gitignore for basic filtering

The primary way Claude Code decides what to ignore is by looking at your .gitignore file. If a file extension or directory is already excluded from your git repository, the agent will generally respect these rules. This means your node-modules folder, build directories, and environment files are already hidden from the tools the agent uses, such as Glob and Read. If you want to ignore a specific file extension globally for your project, adding it to your .gitignore is the most straightforward method available to you.

This approach works well for files that you never want to track in version control. However, you might have files that you want to keep in git but hide from the coding agent. For example, you might track large documentation PDFs or specific asset files that the agent does not need to read to help you write code. In these cases, relying solely on .gitignore is not enough to maintain a clean context. You must look at configuration files specific to the agent to achieve more granular control over what the agent can access.

Project instructions in CLAUDE.md

You can provide explicit instructions to the agent using a CLAUDE.md file in your project root. This file is designed to hold project-specific guidelines and rules that the agent must follow. You should add a section in this file that tells the agent which file extensions to ignore during its operations. You can write a plain English instruction such as: Do not read or edit any files with the .tmp or .data extension. The agent reads this file at the start of every session and follows the rules established there to guide its behavior.

Using CLAUDE.md is effective because it applies to the entire project tree unless you override it. If you have a complex project with multiple subdirectories, you can place additional CLAUDE.md files in those specific folders. A file in a subdirectory will apply rules specifically to that part of the tree. This allows you to ignore .test.js files in a production directory while allowing them in a test directory. The agent combines these instructions to form its operating logic for each task you assign to it.

Fine-tuning behavior with settings files

The agent uses specific tools like Read, Edit, and Glob to interact with your files. You can control these interactions through the .claude/settings.json file in your project root or .claude/settings.local.json for your own untracked overrides. While you cannot explicitly list ignored extensions in a specific key in these files based on the standard configuration, you can use the permissions key to define how tools behave. Documenting your requirements for these tools within your settings files or CLAUDE.md ensures the agent understands the boundaries of its work.

Configuring these settings helps prevent accidental edits to sensitive or generated files. If you find that the agent often tries to modify your lock files or compiled assets, setting strict instructions in your project files is a helpful safeguard. You can also use the .claude/settings.local.json file to manage local configuration extensions that you want the agent to ignore specifically on your machine. This is useful for developers who have personal log files or temporary scripts that should not be part of the shared project context.

Global configuration for all projects

If you find yourself ignoring the same file extensions across every project you work on, you can use the global configuration file. This file is located at ~/.claude/CLAUDE.md in your home directory. Rules written here apply to every session you start with the claude command, regardless of which folder you are in. This is the best place to put rules for common system files or personal file types that should never be part of a coding conversation across any of your repositories.

For example, you might want to ignore .DS-Store files on macOS or Thumbs.db on Windows across all your work. By adding these extensions to your global instructions, you save yourself from repeating the same setup in every new repository. The agent checks this global file in addition to any project-level CLAUDE.md files. This layered approach gives you a flexible way to manage what the agent can and cannot see based on the context of your work and your personal preferences.

Monitoring agent behavior with adhdTerminal

When you are testing new ignore rules, it is helpful to see how the agent responds across different tasks in real time. If you use adhdTerminal, which is a native app for macOS and Windows made by MINDBALANCER OU, you can run many Claude Code sessions side by side. Each session is a tile on a wall, showing whether it is working, waiting, or idle. You can have one tile testing a prompt in a directory where an extension is ignored and another tile in a different project to compare results visually.

The visual feedback from adhdTerminal makes it easier to catch mistakes in your ignore configuration. If a tile shows that the agent is waiting for you to approve a Read tool call on a file it should have ignored, you know your CLAUDE.md rules need adjustment. Since tiles reopen in the same place after a restart and resume the same session, you can maintain a persistent testing environment for your agent configurations. This saves time compared to searching through a single terminal window for previous tool calls and agent responses across multiple projects.

Using slash commands to verify state

Once you have set up your ignore rules, you can use internal slash commands to check what the agent knows. The /config command shows you the current configuration the agent is using. This helps you verify that your .claude/settings.json or global settings are being loaded correctly. If the agent seems to be ignoring your rules, you can use the /doctor command to check the health of your installation and ensure there are no permission issues preventing it from reading your project instruction files properly.

If a session becomes cluttered because the agent read too many files before you set up your ignore rules, use the /clear command. This starts the session over in the same folder, allowing the agent to pick up your new CLAUDE.md rules from a clean state. This is often faster than trying to explain the new rules mid-conversation. Starting fresh ensures that the agent's internal memory does not contain information from files you now want to keep private or hidden from its view.

Managing session context and cost

Ignoring unnecessary file extensions is directly tied to the cost and performance of your sessions. Every time the agent reads a file, it contributes to the spend you see when you run the /cost or /usage commands. By excluding large assets or unnecessary code, you keep your per-task costs lower. This is especially important for long-running sessions where the conversation history grows quickly. While /compact can help summarize what has happened, preventing the data from entering the context in the first place is always better.

The agent's ability to search your project using Grep or Glob is also affected by your ignore rules. If you tell the agent to ignore .json files in a specific directory, its search results will be cleaner and more relevant to your actual coding task. This reduces the cognitive load on the agent and results in more accurate answers. Managing your environment effectively ensures that Claude Code remains a helpful tool rather than a source of confusion or excessive expense. You can also use adhdTerminal to keep an eye on the numbers and headlines each project publishes to monitor these efficiencies.

Questions people ask

Can I ignore files that are not in my gitignore file?

Yes, you can use the CLAUDE.md file in your project root or subdirectories to specify files and extensions to ignore. Write clear instructions like 'Do not read or use files with the .log extension' to guide the agent. This is the best way to hide files that you want to keep in your repository but keep away from the agent's context.

How do I check if my ignore rules are working correctly?

You can monitor the tool calls the agent makes during a session. If you see the agent using the Read or Edit tools on files you intended to ignore, your instructions may need to be more specific. You can also use the /config command to verify that your settings files are being loaded as expected by the agent.

Does ignoring file extensions reduce the cost of using the agent?

Yes, it reduces costs by preventing the agent from reading large or irrelevant files into the context window. Fewer tokens processed means lower costs per task. You can track these savings by using the /cost and /usage commands to see the impact of your filtering rules.

Read next

More on claude code basics·All posts