HOW-TO · DEV

How to configure Claude Code's forbidden tool restrictions for safe usage

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

Claude Code CLI installed, project directory with a config file

What this does

Claude Code can invoke system tools such as shell commands, file write operations, and package installations. The forbidden tools configuration allows administrators to restrict which tools the CLI can use, preventing unintended shell execution, file modifications, or package installations in sensitive environments such as production servers or shared CI runners.

Steps

  1. Locate or create the Claude Code configuration file. The tool reads from ~/.config/claude-code/config.json for global settings or .claude-code.json within a project directory for per-project overrides.
  2. Open the config file in a text editor. If it does not exist, create a new JSON file with an empty object {} as the starting point.
  3. Add a forbiddenTools key to the configuration object. This key accepts an array of tool names as strings.
  4. Specify the tools to restrict. Common restrictions include "bash" to prevent shell command execution, "write" to prevent file creation, and "install" to prevent package manager operations.
  5. Save the configuration file. The changes take effect on the next Claude Code session.
  6. Test the restriction by launching Claude Code and attempting to use a forbidden tool, for example by asking it to run ls if bash is disabled. The tool should return a permission denied message.
  7. For granular control, use the allowedPaths key to restrict file operations to specific directories. For example, set "allowedPaths": ["/project/src"] to limit file edits to only the source directory.
  8. Review and update the configuration as project needs change. Use the /tools command within an interactive session to list all currently available and disabled tools.

Verification

claude /tools

Expected output:

Available tools: read, glob, grep, web-search
Disabled tools: bash, write, install
Reason: forbiddenTools configuration

Common failures

  1. Malformed JSON in config file — A trailing comma or missing bracket causes the configuration to fail to load. Validate the JSON using a tool like jq . < ~/.config/claude-code/config.json to check for syntax errors.

  2. Wrong config file location — The tool checks for per-project config first, then global config. If restrictions are not applied, verify the correct file is being read by checking .claude-code.json in the current directory before the home directory.

  3. Overly restrictive config locks out all operations — Disabling too many tools may prevent Claude Code from completing even basic tasks. Start with minimal restrictions and add only those needed for the specific threat model.

  4. Config changes not reloaded in existing session — Modifications to the config file are not picked up by an already-running Claude Code REPL. Exit and restart the session for changes to take effect.

Related guides

  • Install Claude Code CLI and authenticate with your Anthropic account
  • Use Claude Code in a read-only reviewing mode for security-sensitive environments
← All how-to guidesCourses →