Last updated 13 October 2026
How to set up a .claudignore file
Your terminal agent reads too much data by default
Your terminal agent has a habit of looking at everything in your repository. When you start a session in a large codebase, the agent tries to understand the project structure to be helpful. It uses tools like Glob and Read to explore your files. If you have large build artifacts, dependency folders, or log files, the agent might waste time and tokens processing data that has nothing to do with your code. This behavior increases your costs and makes the agent slower because it has to manage a much larger context window.
Developers often look for a specific configuration file to solve this problem. You might expect a file named specifically for your agent to handle these exclusions. However, you do not need to create a new tool-specific ignore file to manage your terminal agent. The agent is designed to be a good citizen of your existing development workflow. It looks at the configuration you already use to manage your version control system. This approach ensures that your agent sees exactly what you see when you are looking at your source code in a standard editor.
Claude Code respects your existing git configuration
Claude Code respects your .gitignore file by default. This is the primary way you control what the agent can and cannot see in your project root. When you run the claude command to start a new session, the agent initializes its understanding of the repository. It automatically filters out any files or directories that match the patterns in your git configuration. This means you do not have to maintain two separate lists of ignored files for your project and your AI tools.
If you have a directory like dist or build in your root and it is listed in your git configuration, the agent will skip it. This is important for performance because build outputs are often massive and contain minified code that is difficult for a model to reason about. By relying on your existing setup, the agent stays focused on the source files where you actually do your work. If you find the agent is still reading files it should ignore, your first step should be to check your standard ignore patterns and ensure they are properly formatted.
Exclude heavy dependency folders to save tokens
Managing heavy dependency folders is the most common reason to fine tune your ignore settings. A node modules folder can contain thousands of files and millions of lines of code. If the agent tries to search through these folders using the Grep tool, it can trigger an enormous amount of work. Even a simple glob pattern might return too many results for the agent to handle efficiently. Ensuring these folders are properly excluded keeps your session snappy and prevents the agent from getting lost in third party library code.
The agent uses the Glob tool to find files that match your requests. When it performs a glob search, it follows the rules of your repository. If you have nested directories with their own ignore rules, the agent will respect those as well. This hierarchical approach allows you to have very specific exclusions for different parts of your project. For example, you might want to ignore large data sets in a specific fixtures directory while still allowing the agent to read the actual test files in the same parent folder.
Protect your local secrets from accidental reads
Privacy and security are major concerns when using a command line coding agent. You likely have files like environment variables or encryption keys that stay on your local machine and never get pushed to a remote server. If these files are not in your ignore list, the agent could potentially read them. While the agent has internal safety guidelines, it is much safer to prevent it from accessing the data entirely. Listing these sensitive patterns in your configuration ensures that the Read tool never touches them during a session.
You can verify what the agent can see by using the /status slash command inside a session. This command provides an overview of the current state of your session. If you are worried about a specific sensitive file, you can also try to use the Read tool on it directly. If your ignore rules are correctly configured, the agent should report that it cannot access the file. This direct testing gives you peace of mind that your local secrets remain private even while you are using powerful AI tools to assist with your development tasks.
Use project settings for more granular control
Sometimes you want to exclude files from the agent without adding them to your git history. You might have personal logs, scratchpad files, or temporary research notes that you want to keep in the repo but hide from the AI. For this, you can use the settings.json file in the .claude directory of your project or the settings.local.json file for your own overrides. These files allow you to configure permissions and behaviour specific to the agent without changing your project for everyone else.
Inside the settings file, you can find a section for permissions. This allows you to set default behaviours for different tools. If you want to be extremely careful, you can change the permission mode using Shift+Tab inside a session. The default mode usually asks for permission before the agent performs sensitive actions like editing files. By moving to the plan mode, you can see what the agent intends to do before it uses any tools. This provides an extra layer of visibility into how the agent is interacting with your filesystem.
Manage multiple sessions effectively with adhdTerminal
If you are working on a large project with many moving parts, you might find yourself switching between different subdirectories frequently. Starting a new session in each directory helps keep the agent focused, but managing multiple terminal windows can become chaotic. This is where adhdTerminal becomes a useful addition to your workflow. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It allows you to run many Claude Code sessions side by side, each one a tile on a wall.
A tile has a colour, a number, and a name. It shows whether it is working, waiting for you, done, or idle. If you have a specific session dedicated to a part of the tree with very strict ignore rules, you can name that tile accordingly. The app even mirrors your wall to a free iPhone app over an end to end encrypted link, so you can check on a long running task while you are away from your desk. It costs 99 dollars once, and one key runs one computer at a time. There is a 7 day free trial and no account is required.
Apply global and local configuration overrides
Customising the agent behaviour across all your projects is possible through the global configuration. You can find a settings file in your home directory under the .claude folder. This global settings file is where you can put rules that you want to apply every time you run the claude command. If you have a specific naming convention for temporary files that you use across every repository, adding them to a global ignore pattern ensures you never have to configure them twice.
There is also a special markdown file called CLAUDE.md that you can place in the root of your project or in any subdirectory. While this file is primarily used for project instructions, you can use it to give the agent explicit guidance on which files it should prioritise or avoid. The agent reads this file at the start of a session to understand the context of the code it is working on. If you tell the agent in this file to never look at a certain subdirectory, it will follow that instruction as part of its project guidelines.
Monitor tool usage to verify your ignore rules
When your project grows, your context window can fill up quickly even with good ignore rules. Every file the agent reads and every command it runs takes up space in the session memory. If you notice the agent starting to forget earlier parts of the conversation or becoming less coherent, it might be time to use the /compact command. This command summarises the session so far and frees up space in the context window. It is a vital tool for maintaining performance during long development sessions.
The agent also provides hook events that you can use to monitor its behaviour. Events like PreToolUse and PostToolUse allow you to see exactly when and how the agent is using tools like Read or Write. If you are a power user, you can set up hooks to log these events or even trigger external scripts. This level of transparency is excellent for debugging complex ignore logic. If you see the agent repeatedly trying to access an ignored file, the hooks will show you the exact sequence of events that led to that attempt.
Keep your context window clean and cost effective
The cost of running an agent is directly tied to the number of tokens it processes. You can monitor your spend at any time using the /cost or /usage commands inside your session. If you see a sudden spike in cost after a simple prompt, it is a strong indicator that the agent just read a massive file that should have been ignored. By keeping your ignore rules tight and your sessions focused, you can keep your development costs predictable and avoid unnecessary spend on irrelevant data.
If you ever need to start over because a session has become too cluttered with irrelevant file data, the /clear command is your best option. It wipes the current conversation history while keeping you in the same folder. This is often faster than quitting and restarting the agent entirely. Once you have cleared the session, you can refine your ignore rules and try your prompt again. This iterative process of tuning your environment ensures that your terminal agent remains a high performance tool for your daily work.
Questions people ask
Can I use a different file name for ignoring files?
Claude Code does not currently support a dedicated ignore file with a custom name. It relies on the standard .gitignore file found in your repository root or subdirectories. If you need to exclude files without adding them to git, you can use the .claude/settings.local.json file to manage specific permissions for the agent.
How do I check if a file is being ignored?
You can run a search command like Grep or Glob inside the session and look for the file in question. If the file is properly ignored, the agent will not return it in the search results. You can also use the /status command to see an overview of the current session state and project configuration.
What happens if I accidentally let the agent read a huge directory?
You can press the Escape key once to interrupt the agent while it is working. If the directory has already been read into the context, use the /compact command to summarise the session and remove the bulk data. For a completely fresh start without the large files in memory, use the /clear command.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.