Last updated 13 October 2026
Running Claude Code in read-only mode
The risk of unintended code modifications
You often need to explore a complex codebase without the risk of changing it. When you point a coding agent at a legacy repository, you want explanations and maps. You do not want the agent to start refactoring logic or fixing typos until you are ready. Claude Code is an active agent that uses tools like Edit and Write to change your files. If you ask a broad question about how a function works, the agent might decide that the function needs an update to be clearer. Without strict boundaries, it might execute these changes before you can intervene.
Accidental writes are especially dangerous when you work on sensitive branches or in production-adjacent environments. Even a well-intentioned edit can break a build or change the behavior of a critical system. You need a way to force the agent into a spectator role. This allows you to leverage its ability to read and analyze code while keeping your files exactly as they are. You can achieve this safety by combining configuration files, project instructions, and manual permission modes.
Configuring global read-only behavior in settings
The most effective way to enforce a read-only environment is through the settings.json file. You can find this file in the .claude directory of your home folder for global changes. Inside this file, there is a section for permissions. You can define the default behavior for every tool the agent uses. By setting the permissions for the Edit tool and the Write tool to a restricted state, you ensure the agent cannot modify files without explicit permission.
If you want to apply these rules to every project on your machine, edit ~/.claude/settings.json. If you only want to protect a specific project, create a .claude/settings.json file in that project root instead. When the agent starts, it checks these files to see what it is allowed to do. If it tries to use the Write tool while the setting is restricted, it will stop and wait for your input. This creates a hard wall that the agent cannot pass on its own. You can also use the /config command inside a session to see which settings are currently in effect for your environment.
Using project instructions to set boundaries
Every project should have a CLAUDE.md file in its root directory. This file is the first thing the agent reads when you run the claude command. It provides the context and rules for the session. To create a read-only environment, you should add clear instructions to this file. Tell the agent that it must never use tools that modify the filesystem. Explicitly list the tools it should use instead, such as Read, Glob, Grep, and Bash for discovery purposes only.
You can be very specific in CLAUDE.md about what constitutes an acceptable action. For example, you can tell the agent that it is allowed to use the Read tool to look at source files but it is forbidden from using the TodoWrite tool. Since the agent refers back to this file throughout the session, it serves as a constant reminder of the safety constraints. If you have subdirectories that require even stricter rules, you can place additional CLAUDE.md files in those folders. The agent will respect the instructions found in the specific branch of the tree where it is working.
Enforcing safety through permission modes
Claude Code has built-in permission modes that change how it handles tool requests. You can cycle through these modes by pressing Shift+Tab while in an active session. The default mode usually asks for permission before major changes, but you can move to the plan mode for higher safety. In plan mode, the agent must stop and present its intended actions for every tool use. This gives you a chance to see if it plans to use the Edit tool before any code is touched.
Using the bypassPermissions mode is the opposite of what you want for a read-only environment. That mode allows the agent to run tools without asking you at all. Always check your current mode by looking at the status bar in your terminal. If you are exploring code and want to be sure nothing changes, staying in the default or plan mode is essential. If the agent ever starts a task that looks like it might involve writing to a file, you can press the Escape key to interrupt the process immediately. Pressing Escape twice will even let you go back to earlier messages and redirect the conversation.
Managing parallel read-only sessions
When you are auditing a large system, you might need to look at several repositories at once. Managing five different terminal windows for five different microservices is difficult. This is where adhdTerminal becomes a useful tool for your workflow. It allows you to run many Claude Code sessions side by side as tiles on a single wall. You can set up each tile for a different repo and apply read-only instructions to each one. This helps you maintain a bird-eye view of your entire system without losing track of which session is which.
Each tile in adhdTerminal shows whether the agent is currently working or waiting for you. If you are running multiple read-only explorations, you can see at a glance if one agent has finished explaining a complex module. The tiles resume the same session after a restart, so your read-only configuration stays active. You can even use the iPhone app to check on the progress of a long code analysis while you are away from your desk. This setup ensures that your research stays organized and safe across multiple projects simultaneously.
Restricting the Bash tool for safe exploration
The Bash tool is powerful because it allows the agent to run shell commands. While this is great for running tests or searching files, it is also a potential source of accidental changes. An agent could run a command that redirects output to a file or deletes a directory. To keep your environment read-only, you must instruct the agent in your CLAUDE.md file to only use Bash for non-destructive commands. Tell it to stick to ls, cat, find, and grep.
You can monitor the output of the Bash tool in real time as the agent works. If you see the agent start to type a command that looks like a write operation, use the Escape key to stop it. You can then use the /clear command if you feel the session context has become too focused on making changes. This starts the conversation over while keeping you in the same folder. Keeping a close eye on the Bash tool is the final step in ensuring that your read-only session does not accidentally turn into an editing session.
Verifying your setup with built-in commands
Before you start a deep dive into your code, use the claude doctor command. This checks your installation and ensures that your configuration files are being read correctly. It is a good way to verify that your environment is stable before you begin a long interaction. Once you are inside a session, you can use /status to see a summary of what the agent has done so far. This includes a list of the tools it has used and the files it has accessed.
If you want to run a quick read-only check without starting a full interactive session, use the claude -p flag. This runs a single prompt and prints the answer. For example, you can ask the agent to explain a specific file and then exit. This is inherently safer because the session ends as soon as the answer is delivered. It prevents the agent from entering a multi-step loop where it might decide to start modifying files. For more complex research, however, the interactive session with restricted permissions is the better choice.
Handling session costs and context
Even in read-only mode, the agent consumes context as it reads your files. Every file the agent accesses with the Read or Bash tools is added to the session context. Over time, this can make the session expensive and slow. You can use the /cost command to see how much you have spent on the current session. If the context window starts to fill up, use the /compact command. This summarizes the conversation so far and frees up space, allowing you to continue your research without losing the core information.
Monitoring your usage with /usage is also a good practice. It helps you understand how much data the agent is processing as it explores your repository. When you are finished with your read-only investigation, you can use /export to save the conversation. This gives you a permanent record of the explanations and insights the agent provided. You can then close the session with Ctrl+C, knowing that your code is exactly as you left it. Following these steps creates a reliable and safe workflow for code analysis.
Questions people ask
Can I still run tests while in read-only mode?
Yes, you can run tests using the Bash tool if your CLAUDE.md instructions allow it. Make sure the tests do not generate or modify source files as part of their execution. You should explicitly tell the agent that it may run test commands but must not change any code to make those tests pass.
What happens if the agent tries to use the Edit tool when I have restricted it?
The agent will encounter a permission error or will stop and ask for your approval depending on your settings in settings.json. If you are in plan mode, it will list the Edit tool as a proposed action and wait for you to type a response. You can then tell the agent to find a different way to answer your question without editing.
How do I temporarily allow writes in a read-only project?
The fastest way is to change the permission mode by pressing Shift+Tab until you reach a mode that allows more freedom. Alternatively, you can use the /config command to adjust tool permissions for the duration of the current session. Once you are done, you should revert the settings or use /clear to return to a safe state.
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.