Last updated 13 October 2026
Make the test folder read-only for Claude
The danger of automated test modification
Claude Code is an agent that works directly in your terminal to help you build software. It uses tools like Read to look at your code and Edit to make changes. A common problem occurs when the agent tries to fix a bug but ends up breaking your tests. Instead of updating the logic to pass the existing test suite, the agent might decide that the test itself is wrong. It then uses the Edit tool to change your test files so they match the broken behavior of the code. This is frustrating for developers who rely on tests as a source of truth for their project requirements.
You need a reliable way to make specific folders read-only for the agent. This prevents accidental changes to your documentation, your test suites, or your configuration files. By setting these boundaries, you ensure that the agent remains a helpful assistant rather than an overzealous editor that rewrites your project history. You want the agent to read your tests to understand how the code should work, but you never want it to change those tests without your explicit oversight and manual confirmation in a separate editor. This level of control is necessary for maintaining the integrity of a large codebase while using automation.
Configuration files for tool management
Configuration for the agent happens in specific JSON files. You can find these in the root of your project at .claude/settings.json or use .claude/settings.local.json for overrides that you do not want to commit to version control. If you want a rule to apply to every project on your machine, use the settings file located in your home directory at ~/.claude/settings.json. These files allow you to define how tools behave when they interact with your file system and which permissions are granted by default.
When you modify these settings files, you are setting the ground rules for every session you start with the claude command. The agent checks these files to determine if it has permission to use tools like Edit or Write on specific file paths. By organizing your settings early, you save yourself from having to manually deny permission requests repeatedly during a long coding session. This systematic approach ensures that your safety preferences are persistent across restarts and different terminal windows.
Restricting tool access to specific paths
You must edit the permissions section within .claude/settings.json to restrict specific tools. The agent relies on tools like Edit and Write to modify your files. By defining rules in your configuration, you can set these tools to a denied status for specific file patterns. For example, you can target any path that includes the string for your test directory or your documentation folder. When the agent attempts to use a tool on a restricted path, it will stop and report a failure or ask for your permission depending on your current mode.
The permissions configuration is the most direct way to enforce a read-only policy. It does not rely on the agent following instructions; it creates a technical boundary that the software must respect. You can set these rules globally in your home directory or locally within a single project. This flexibility allows you to have strict rules for core libraries while being more relaxed with experimental scripts. If you are ever unsure about the current settings, the /permissions slash command provides a quick summary of what the agent can and cannot do in the active session.
Explicit instructions in project markdown files
Beyond technical restrictions in settings files, you should use the CLAUDE.md file in your project root to provide explicit guidance. Write a section in this file that clearly states the test folder is for reference only. Instruct the agent to never attempt to modify files in that directory even if it thinks a test is incorrect. When the agent starts a session, it reads this file to understand the context and rules of your project. This provides a secondary layer of protection that helps the agent reason about why certain folders are off-limits.
A well-maintained CLAUDE.md file acts as a manual for the agent. You can include patterns for your file structure and explain that the Read tool is permitted for tests but the Edit tool is strictly forbidden. This helps the agent avoid making mistakes in its planning phase. While the settings.json file provides the hard enforcement, the CLAUDE.md file provides the logic behind the rules. This combination reduces the number of times the agent will even try to touch your protected files, making the entire interaction smoother and more efficient.
Controlling execution with permission modes
You can change how the agent handles tool requests by cycling through permission modes. By pressing Shift+Tab inside a session, you can switch between default, acceptEdits, plan, and bypassPermissions modes. If you are worried about your test folder, the plan mode is particularly useful. In this mode, the agent focuses on outlining what it intends to do before it ever invokes a tool like Edit or Write. This gives you a clear window to see if the agent plans to modify a file that should remain read-only.
The default mode is also a safe choice because it requires your confirmation for many actions. However, if you have already configured your permissions in settings.json, the agent will know to stop before it even asks you. Understanding these modes allows you to adjust the level of autonomy you give to the agent based on the sensitivity of the task. For routine refactoring where you want to protect your tests, staying in plan or default mode ensures that no file is changed without a clear prompt or a check against your configuration files.
Monitoring multiple sessions with adhdTerminal
When you are running several Claude Code sessions across different branches or microservices, keeping track of permission prompts becomes difficult. This is where adhdTerminal becomes useful as it lays out all your sessions as tiles on a single wall. Each tile has a color, a number, and a name, showing you exactly what each agent is doing. You can see at a glance if a session is working, waiting for your input, or sitting idle. This visual overview is essential when you have multiple agents working under different read-only restrictions.
If a session hits a permission error because it tried to edit a protected folder, the adhdTerminal tile shows the status clearly. You do not have to scroll through multiple terminal tabs to find which agent stopped. The wall of tiles keeps the last exchanges of every conversation visible, so you can quickly see why an agent tried to access a restricted path. This helps you manage the cognitive load of supervising several autonomous tasks at once while ensuring that none of them violate the boundaries you set in your settings.json files.
Applying local rules to subdirectories
Sometimes you only want to protect a specific part of a large project. You can place a CLAUDE.md file inside a subdirectory to apply rules specifically to that part of the file tree. If your tests are nested deep within a source folder, a CLAUDE.md file in that specific directory can reinforce the read-only requirement for that branch. The agent respects the instructions in the closest CLAUDE.md file it finds when it is working in a subdirectory, allowing for granular control over different modules.
This approach is helpful for large repositories where different teams might have different standards for automation. You can protect the core documentation in one folder while allowing the agent more freedom in a sandbox or experimental folder. By combining subdirectory instructions with the global settings in your home directory, you create a tiered system of permissions. The agent uses the Glob and Grep tools to understand the structure, and your local instructions guide how it applies the Edit tool within those specific boundaries.
Testing your permission configuration
After you have modified your settings.json and CLAUDE.md files, you should verify that the agent respects the new boundaries. You can do this by running a single prompt using the command claude -p followed by a request to modify a file in the protected folder. If your configuration is correct, the agent should report that it does not have permission to perform that action or that it is prohibited by your project instructions. This quick test confirms that your safety net is active before you begin a complex task.
You can also use the /permissions slash command inside an interactive session to check the current state of tool authorizations. This command lists which tools are allowed or denied and shows the patterns they apply to. If you see that the Edit tool is still allowed for your test folder, you may need to check the syntax in your .claude/settings.json file. Ensuring that your patterns correctly match the file paths is vital. Regular verification prevents the agent from making unwanted changes because of a small typo in a configuration file.
Managing session history and mobile oversight
As you work, the session context window fills up with the history of your conversation and the files the agent has read. If the agent repeatedly tries to access a test folder despite your restrictions, it might be worth using /compact to summarize the session and clear out the failed attempts. This keeps the agent focused on the valid paths you have allowed and prevents the context from becoming cluttered with permission errors. If the agent becomes completely confused by the restrictions, you can use /clear to start over in the same folder while keeping your settings in place.
If you need to step away from your desk while an agent is running a long task, the adhdTerminal iPhone app can mirror your wall of tiles over an end to end encrypted link. You can see the status of every session and check if an agent is stuck on a permission prompt or if it has finished its work. The app allows you to answer a prompt or send the next task from your phone. This is an honest way to keep an eye on your restricted folders and ensure the agent is following the rules you set in your configuration files even when you are not at your computer.
Questions people ask
What happens if the agent needs to update a test because of a legitimate change?
If you are in the default permission mode, the agent will prompt you for approval before it uses the Edit tool on a protected file. You can review the proposed change in your terminal and choose to allow it for that single instance. This keeps you in control of your test suite while still allowing for necessary updates.
Can I use wildcards to protect multiple folders at once?
Yes, you can use glob patterns in your settings.json file to cover multiple directories like tests, docs, and config. The agent uses the Glob tool to navigate files, and your permission settings can use similar patterns to block access. This allows you to protect all non-source folders with a single rule.
How do I revert a change if the agent ignores my instructions?
If the agent makes an unwanted change, you can use the Escape key twice to see earlier messages and go back to a previous state in the conversation. You can also use your own version control system to discard any edits to the protected folders. Using /clear will also reset the current session context if the agent becomes stuck in a loop of trying to edit restricted files.
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.