Last updated 13 October 2026
Stop Claude Code reading large binary files
Binary data consumes your context window and budget
Your terminal might fill with nonsense characters or your token count might spike because the agent tried to read a JPG or a compiled DLL. Claude Code uses the Read and Glob tools to explore your workspace and identify relevant files. If it encounters a large binary file, it might try to ingest the contents. This wastes your context window and your money. The agent is a text model, so it cannot interpret raw binary data meaningfully. It simply sees a wall of encoded text that displaces your actual code logic.
When the context window is full of binary noise, the agent loses track of earlier instructions. It might forget the specific requirements of your task or lose the ability to recall function signatures from other files. Because you pay for the tokens used in each exchange, reading a single high-resolution image or a large PDF can cost as much as several hours of actual coding work. Preventing this behavior is a matter of both performance and cost management.
The agent respects your existing gitignore rules
Claude Code respects your .gitignore file by default. This is the first line of defense against unwanted file indexing. Ensure your build artifacts, dependencies, and media folders are correctly listed in the root .gitignore of your repository. If a file is ignored by git, the agent usually ignores it during search and read operations. This keeps the Glob and Grep tools from surfacing files that do not belong in the conversation.
Check your .gitignore for missing binary extensions like .pyc, .exe, .so, or .dmg. Developers often forget to ignore local database files or log files that grow over time. If the agent sees these files, it might assume they are part of the source code. By keeping your .gitignore strict, you ensure the agent only sees the files that actually matter for the development process. This is the most efficient way to filter project data without creating new configuration files.
Project specific instructions belong in CLAUDE.md
You can provide explicit rules in the CLAUDE.md file to guide the agent. This file sits in your project root and serves as the primary manual for the agent behavior. Write a section in CLAUDE.md titled File Access Rules and list the extensions or directories the agent must never open. Use plain English to tell the agent to skip images, PDFs, and executable files. Since the agent reads CLAUDE.md at the start of the session, it will keep these instructions in its active memory.
If you have a subdirectory that contains both code and large assets, place a second CLAUDE.md in that subdirectory. This file applies specifically to that part of the tree. You can instruct the agent to only use the Read tool on files with specific extensions like .js or .go within that folder. This granular control prevents the agent from accidentally triggering a read on a large binary asset while it is exploring a legitimate code directory. Explicit instructions in these files are more effective than relying on the agent to guess what is a binary.
Global rules apply across all your projects
For preferences that apply to every project on your machine, use the CLAUDE.md file located in your home directory at ~/.claude/CLAUDE.md. This is the best place to define a permanent list of binary extensions that you never want any agent session to touch. By placing your ignore rules here, you protect yourself from accidental token waste even when you are working in a new or unconfigured repository. The agent checks this global file in addition to any local project instructions.
Common global exclusions should include standard media formats and compiled binaries. You might list .png, .jpg, .pdf, .zip, and .tar as types to always avoid. If you frequently work with data science projects, you might also exclude .parquet or .sqlite files by default. Setting these rules at the user level ensures a consistent experience across different terminal sessions. It also saves you from having to recreate the same ignore logic every time you start a new project with the claude command.
Slash commands help you recover from accidental reads
When the context window becomes heavy with accidental data, use /compact. This command summarizes the session history and clears out the bulky details of previous tool outputs. If the agent has already read a massive binary file and the session is now sluggish, /compact is the fastest way to recover space. It distills what was learned without keeping the raw binary contents in the active context. This is essential for maintaining speed in long-running sessions.
If an entire session is corrupted by bad data or the agent is hallucinating based on binary noise, use /clear to start fresh in the same folder. This resets the state without losing your project instructions or your login status. It is better to start over than to struggle with an agent that has a context window full of garbage. You can also use /status to see a summary of the current session state and determine if the agent is carrying too much baggage from previous tool calls.
Tool permissions offer a manual safety gate
You can control tool behavior through the .claude/settings.json file. This file allows you to set permissions for specific tools used by the agent. While the settings schema does not allow you to block specific file types directly, you can set the agent to request permission before using certain tools. By default, the agent operates in a mode that may allow it to read files without asking. You can change this behavior to ensure you see what the agent is doing before it happens.
Use the Escape key to interrupt the agent if you see it starting to read a file that you know is a large binary. Pressing Escape once stops the current tool execution. This is your immediate manual override when you notice a mistake in the terminal output. If you have already made a mistake, pressing Escape twice offers you a list of earlier messages. You can select a point before the binary was read and return to that state, effectively undoing the accidental read and saving your context.
Monitor multiple sessions to catch issues early
Managing these exclusions across a dozen microservices is difficult to track in a single terminal window. It is easy to miss a spike in token usage if you are switching between tabs. adhdTerminal solves this by displaying multiple Claude Code sessions as tiles on a wall. You can see at a glance whether a session is working or idle and check the last few exchanges of the conversation without clicking through multiple terminal buffers.
Each tile in adhdTerminal shows the status of the session, making it obvious if an agent has wandered into a folder of high-resolution assets and is struggling to process them. Because the tiles show numbers and headlines the project publishes, you can monitor cost and progress across several repositories simultaneously. This visibility helps you catch misconfigured ignore rules before they result in a significant bill. The iPhone app also allows you to monitor these sessions remotely and stop an agent if it starts misbehaving.
Verify your configuration with built-in tools
Use the /config command to verify that your settings are active. This command prints the current configuration the agent is using, including any overrides you have set in .claude/settings.json or .claude/settings.local.json. If you are unsure if your home directory instructions are being picked up, this output will confirm the active path. Checking the configuration regularly ensures that your token-saving rules are actually in effect and that the agent is not ignoring your CLAUDE.md instructions.
The /doctor command is another useful tool for checking the health of your installation. While it focuses on the environment and dependencies, it can help identify if there are issues with how the agent accesses your file system. If the agent is consistently failing to respect ignore rules, /doctor might reveal permission issues or path configuration errors. Ensuring a healthy installation is the final step in maintaining a clean and efficient coding environment.
Questions people ask
How can I tell if Claude Code is currently reading a binary file?
Watch the terminal output for the Read tool usage. If the agent begins outputting a long stream of random characters, base64 data, or symbols, it has likely opened a binary file. You should immediately press the Escape key once to interrupt the process and then use /compact to clear the noise from the context.
Can I use a custom ignore file specifically for the agent?
There is no dedicated ignore file for Claude Code, but it respects .gitignore. If you need to ignore files specifically for the agent without affecting your git repository, use the CLAUDE.md file. Write a clear instruction telling the agent to ignore specific patterns or directories during its operations.
Does /compact remove the binary data from the session permanently?
Yes, /compact summarizes the conversation so far and removes the raw output of previous tool calls from the active context window. This includes the contents of any large files the agent read. The agent will remember that it read the file and what the summary of the file was, but the bulky binary data will no longer occupy space.
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.