RUNLOCALAIv38
->Will it run?Best GPUCompareTroubleshootStartLearnPulseModelsHardwareToolsBench
Run check
RUNLOCALAI

Independently operated catalog for local-AI hardware and software. Hand-written verdicts. Source-cited claims. Reproducible commands when we have them.

OP·Eruo Fredoline
DIR
  • Models
  • Hardware
  • Tools
  • Benchmarks
TOOLS
  • Will it run?
  • Compare hardware
  • Cost vs cloud
  • Choose my GPU
  • Prompting kits
  • Quick answers
REF
  • All buyer guides
  • Learn local AI
  • Methodology
  • Glossary
  • Errors KB
  • Trust
EDITOR
  • About
  • Author
  • How we make money
  • Editorial policy
  • Contact
LEGAL
  • Privacy
  • Terms
  • Sitemap
MAIL · MONTHLY DIGEST
Get monthly local AI changes
Monthly recap. No spam.
DISCLOSURE

Some links on this site are affiliate links (Amazon Associates and other first-class retailers). When you buy through them, we earn a small commission at no extra cost to you. Affiliate links do not influence our verdicts — there are cards we rate highly that we don't have affiliate relationships with, and cards that sell well that we refuse to recommend. Read more →

© 2026 runlocalai.coIndependently operated
RUNLOCALAI · v38
  1. >
  2. Home
  3. /Learn
  4. /How-to
  5. /How to configure Claude Code's forbidden tool restrictions for safe usage
HOW-TO · DEV

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

intermediate·10 min·By 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 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 →