Last updated 13 October 2026
Fix Claude Code ignoring files in gitignore
The gitignore behavior of the agent
Claude Code aims to be a helpful partner by reading your project files and suggesting changes. It uses tools like Read, Glob, and Grep to find its way around your repository. Usually, it follows the rules you have already set in your .gitignore file. This means it should stay away from your build folders, local environment variables, and large dependency trees like node_modules. If it behaves correctly, you never have to worry about sensitive data leaking into the context window of the agent.
However, you might see the agent suggesting edits to a file you thought was hidden. Or it might spend a long time searching through a directory that has nothing to do with your current task. This happens when the internal logic of the agent or the tools it calls do not align perfectly with how Git interprets exclusion patterns. Fixing this requires a mix of project instructions and explicit configuration settings. You need a way to tell the command line tool that your ignore rules are not suggestions but strict boundaries for its operations.
Identifying file visibility issues
Before you change any files, you need to know exactly what the agent can see. Start a session with the claude command and use the /status command to get a summary of the current environment. You can also directly ask the agent to list the files in a specific directory using a simple prompt. If it identifies a file that is supposed to be ignored by Git, you have confirmed the leak. This evidence is necessary to determine if the problem is a broad search issue or a specific file access failure.
Another useful step is running claude doctor from your terminal. This command checks your installation and environment to ensure everything is functioning as expected. It does not specifically report on .gitignore parsing, but it can find issues with how the agent interacts with your shell. If your shell path or permissions are misconfigured, the agent might struggle to use standard tools correctly, leading to unexpected file access. Always ensure your environment is clean before you start applying complex exclusion rules to your repository.
Project level settings for path exclusion
The most reliable way to force the agent to ignore specific files is through the .claude/settings.json file. This file sits in your project root and controls how the agent behaves. You can find a section for permissions where you can define rules for specific tools. If you want to stop the agent from reading a file, you can explicitly deny the Read tool for that path. This creates a hard barrier that the agent cannot cross even if it tries to use its internal file reading logic.
If you do not have a .claude/settings.json file yet, you can create one manually or use the /config command inside a session to see your current options. Adding your exclusion patterns here is more powerful than relying on .gitignore alone because it is specific to the agent. This ensures that even if a Git command would technically see a file, the agent is hard-coded to ignore it. This is the best place for blocking sensitive files like local keys, database dumps, or large binary files that would otherwise clutter your session.
Global configuration for consistent privacy
You might have certain files that you never want any AI agent to see across any of your projects. These could be global logs, temporary editor files, or personal configuration scripts. Instead of adding these to every single repository, use the global settings file located at ~/.claude/settings.json. The agent reads this file every time you start a new session regardless of which folder you are in. This provides a consistent layer of protection for your entire development machine.
Settings in your home directory act as a safety net. If you forget to set up a local .claude folder in a new project, your global rules still apply. This is a proactive way to maintain your privacy and keep the agent focused on code rather than your system files. When you run claude, it merges these global settings with your project-level ones, giving you a layered defense against accidental file exposure. It is a good practice to keep this file updated with common patterns like backup files or temporary build artifacts.
Instruction based guarding with project files
The CLAUDE.md file is a special markdown document that the agent reads to understand your project. It usually contains build commands, style guides, and test instructions. You can also use it to set boundaries for file access. Create a section in CLAUDE.md that lists directories the agent should not enter. Use plain language to tell the agent that it must not use Glob or Grep on these specific paths. This adds a layer of intelligence to your file exclusion strategy.
Instruction-based ignoring is very effective because it guides the agent's planning phase. When the agent uses the Task tool to break down a problem, it will see your instructions in CLAUDE.md and avoid those files in its plan. This prevents the agent from even trying to access the files in the first place. It is a soft limit that complements the hard limits you set in your JSON configuration files. By telling the agent why a folder is ignored, you help it understand the project structure better.
Managing multiple project boundaries
Managing file exclusions becomes more complex when you are working on multiple microservices or different branches of the same project. If you are using adhdTerminal, you can manage this by looking at your wall of tiles. Each tile shows a different claude session with its own name and color. This native app for macOS and Windows lets you run many Claude Code sessions side by side. You can quickly see if a session is working or waiting for you. The wall helps you keep track of which projects have specific exclusion rules enabled without switching between terminal tabs constantly.
By separating your work into these tiles, you can apply different ignore rules to each one. A backend session might need access to certain configuration files that the frontend session should never touch. The adhdTerminal interface allows you to see the last few exchanges for each session at a glance. If you notice a tile is processing a file it should not be, you can jump in and correct the instructions in that specific folder without affecting your other active tasks. This visual organization helps you maintain strict control over file access across complex projects.
Localized rules for specific subdirectories
In large repositories, a single list of ignored files might be too restrictive or not detailed enough. You can place a CLAUDE.md file in any subdirectory to provide local context. The agent will read the CLAUDE.md in the root first, and then the one in the subdirectory when it moves into that part of the file tree. This is perfect for monorepos where different teams have different standards for what should be hidden. It allows for a modular approach to project instructions.
Subdirectory instructions allow you to be very specific about local build artifacts or documentation folders that are not globally ignored but are irrelevant to the code. If you have a folder full of large assets or generated data, telling the agent to ignore it locally keeps the context window focused. This prevents the Glob tool from returning hundreds of useless results when the agent is looking for a specific function definition. It also ensures that the agent does not waste time analyzing files that do not impact the current coding task.
Resetting session memory for new rules
If you have updated your .gitignore or your settings files but the agent still seems to remember the old files, you need to clear the session. Use the /clear command to wipe the current conversation history and start fresh. The agent keeps a running memory of what it has seen, and a change in your file system does not always trigger an immediate update in its internal state. Clearing the session forces it to start over with the new rules in place.
If the problem persists after a clear, use claude --resume to see if you are accidentally carrying over state from an older session that had different permissions. You can also check .claude/settings.local.json for any personal overrides that might be causing the issue. This local file is often used for personal preferences that you do not want to commit to the repository, and it can sometimes contain outdated path exclusions. Comparing your local settings with the repository settings can reveal conflicts that lead to unexpected file access.
Maintaining context cleanliness and security
Maintaining a clean environment for your coding agent is a continuous task. Regularly check your spend with the /cost and /usage commands to see if the agent is wasting tokens on large, irrelevant files. If you see a spike in costs, it is a sign that your exclusion rules are not tight enough. The agent might be reading more than it needs to, which slows down its performance and increases your bill. Constant monitoring is the only way to ensure your configuration remains efficient.
Use the /compact command often to keep the context window small. This not only saves money but also forces the agent to rely on the most relevant information. When the context is tight, the agent is less likely to wander into ignored directories. By combining strict path permissions in .claude/settings.json with clear instructions in CLAUDE.md, you create a predictable and secure environment for your development work. This setup ensures the agent stays within its boundaries while providing the help you need.
Questions people ask
Can I use a specific ignore file just for Claude Code?
You can use the .claude/settings.json file to list patterns that function like a private ignore list. This file allows you to specify paths that the agent should never interact with regardless of your Git settings. It is the most direct way to control the agent without changing your shared project configuration.
What happens if I add a file to gitignore after starting a session?
The agent might still have the file in its context until you refresh the state. Use the /clear command to wipe the current conversation and start fresh with the new rules in place. This ensures the agent no longer sees the file when it uses the Glob or Read tools.
How do I ignore very large files that slow down the agent?
List these large files or directories in your root CLAUDE.md file under a clear heading for project constraints. You can also block access to them in .claude/settings.json by denying the Read tool for those specific paths. This prevents the agent from filling the context window with useless data and saves you tokens.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.