HOW-TO · DEV

How to use Claude Code in a read-only reviewing mode for security-sensitive environments

intermediate10 minBy Eruo Fredoline
Target environment
Ubuntu 24.04 · Claude Code 1.xmacOS 14.x · Claude Code 1.x
PREREQUISITES

Claude Code CLI installed, project directory with code to review

What this does

Security-sensitive environments such as production systems, regulated industries, or shared development servers require that CLI tools cannot modify files or execute arbitrary shell commands. Claude Code supports a read-only reviewing mode that enables code analysis, inspection, and review workflows while explicitly blocking all write operations, shell execution, and package management operations.

Steps

  1. Create or edit the Claude Code configuration file at ~/.config/claude-code/config.json or .claude-code.json in the project root.
  2. Add a readOnlyMode key set to true within the configuration object.
  3. Also add forbiddenTools with at least ["bash", "write", "install", "edit"] to ensure write operations are blocked even if the primary flag is not respected in some contexts.
  4. Set allowedPaths to an array containing only the directories that the tool should be able to read, for example ["./src", "./tests"]. This prevents traversal into sensitive system directories.
  5. Save the configuration file and exit the editor.
  6. Launch Claude Code in the target project directory using claude.
  7. Verify the restricted state by running /tools. The output should show only read-only tools such as read, glob, and grep as available.
  8. Initiate a review by reading files with /read and analyzing the code. Attempting to use a write tool produces a permission denied message.
  9. Run code analysis on a specific file by prompting for patterns, for example "Identify all hardcoded credentials in this codebase" or "Find potential SQL injection points in the API handlers".
  10. Generate a review report in memory by asking for a summary, then copy the output to a secure location outside the restricted workspace.

Verification

claude /tools

Expected output:

Read-only mode: enabled
Available tools: read, glob, grep, web-search
All write operations blocked

Common failures

  1. Read-only mode not recognized by older CLI version — Ensure the installed version of Claude Code is 1.0 or higher. Run claude --version and upgrade using npm install -g @anthropic-ai/claude-code if needed.

  2. Path traversal attempted outside allowed directories — When allowedPaths is set, any /read command targeting a path outside the allowed list returns a permission error. Verify the paths are correctly specified as absolute or properly relative paths in the configuration.

  3. Session not restarted after config change — Configuration changes require a new Claude Code session. If the read-only state is not active, exit the current session and restart.

  4. Glob tool exposes restricted paths — The glob tool respects allowedPaths and only returns files within permitted directories. If unexpected files appear, confirm the allowed paths list does not include parent directories that contain sensitive subdirectories.

Related guides

  • Configure Claude Code's forbidden tool restrictions for safe usage
  • Use Claude Code to review a pull request from the command line
← All how-to guidesCourses →