Claude Code Permissions: Rules, Modes and settings.json

Claude Code permissions explained: allow, ask and deny rules, permission modes, where each settings.json file lives, and a starter config you can copy.

Josh Pocock8 min read

Permissions cover

AI Coding

Permissions

Stride AI Academy

Claude Code permissions are the rules that decide what Claude can do without asking you first. You set them as allow, ask and deny lists in a settings.json file, or with the /permissions command, and a permission mode sets the overall behaviour for the session. Deny rules always win, then ask, then allow.

This guide covers the permission modes, the rule syntax for Bash, Read, Edit, WebFetch and MCP tools, where each settings file lives and which one wins, a starter settings.json and the mistakes that trip people up. Everything here was checked against Claude Code's permissions docs, settings docs, permission modes docs and managed settings docs on November 18, 2026.

How Claude Code permissions work

Some actions never need approval. File reads inside your working directory run freely, and so does a built-in set of read-only shell commands such as ls, cat, grep and read-only forms of git. Everything else depends on your mode and your rules:

Action Asks in Manual mode?
File reads, Grep No, inside your working directories
Bash commands Yes, except the read-only set
File edits and writes Yes
WebFetch Yes, except some preapproved documentation domains
Web search Yes

When you pick "Yes, and don't ask again" on a Bash prompt, Claude Code saves an allow rule to .claude/settings.local.json for you.

Permission rules are enforced by Claude Code itself, not by the model. A note in your CLAUDE.md shapes what Claude tries. A rule decides what it's allowed to do.

Permission modes

The mode sets the default answer for anything your rules don't cover. Press Shift+Tab to cycle modes during a session, or start with a flag such as claude --permission-mode plan.

Mode What runs without asking
default (Manual) Reads only
acceptEdits Reads, file edits and common file commands like mkdir, mv and cp
plan Reads and exploration, no source edits (plan mode)
auto Most actions, after a background classifier checks them
dontAsk Only pre-approved tools; anything that would prompt is denied
bypassPermissions Almost everything

On recent versions, Auto is the built-in starting mode for interactive terminal and VS Code sessions, while claude -p starts in Manual. To pick your own default, set defaultMode in ~/.claude/settings.json:

JSON
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

A project's .claude/settings.json can't set auto or bypassPermissions as the default. Bypass mode skips nearly every check, so it gets its own guide: Claude dangerously skip permissions.

Allow, ask and deny rules

Each rule is either a tool name, like Bash, or a tool name with a specifier, like Bash(npm run build).

  • allow: Claude uses the tool without asking.
  • ask: Claude Code prompts you every time.
  • deny: the action is blocked.

Rules are checked in a fixed order: deny, then ask, then allow. The first match wins, and a more specific rule doesn't jump the queue. So a deny rule for Bash(aws *) blocks aws s3 ls even if you also allow Bash(aws s3 ls).

A bare tool name in deny, such as "deny": ["WebFetch"], removes the tool from Claude's context entirely.

Bash rules

A * matches any text, including spaces. Put it after the subcommand, because everything before the first * is matched as written:

Rule Matches Doesn't match
Bash(npm run build) npm run build npm run build --watch
Bash(npm run *) npm run build, npm run test --watch npm install
Bash(git log *) git log, git log --oneline git push
Bash(ls *) ls, ls -la lsof

Claude Code understands shell operators, so Bash(safe-cmd *) won't approve safe-cmd && other-cmd. Every part of a compound command has to be allowed. Deny and ask rules apply if any part matches.

One limit matters: a Bash rule matches the command text, not the program. A deny rule for Bash(rm *) stops rm -rf build/ but not /bin/rm -rf build/ or bash -c 'rm -rf build/'. For a hard boundary, use the sandbox or a PreToolUse hook.

Read and Edit rules

Read and Edit rules use gitignore-style patterns. The leading characters change where the path starts:

Pattern Means Example
//path Absolute path from the filesystem root Read(//Users/alice/secrets/**)
~/path From your home directory Read(~/.zshrc)
/path From the settings file's root (the project, for project settings) Edit(/src/**/*.ts)
path or ./path From the current directory Read(./.env)

A Read deny rule also blocks Edit and Write on that path. Edit rules cover every built-in tool that edits files. Rules written as Write(path), Grep(path) or Glob(path) are accepted but don't match anything, so use Edit or Read instead.

WebFetch rules

WebFetch rules use a domain: prefix. WebFetch(domain:example.com) covers that host only. Add WebFetch(domain:*.example.com) to cover its subdomains.

MCP tool rules

MCP tools are named mcp__<server>__<tool>:

  • mcp__github__* matches every tool from a server named github
  • mcp__github__get_* matches its tools that start with get_
  • mcp__* as a deny rule blocks every MCP tool on every server

Allow rules for MCP tools take no specifier in parentheses. If you're still adding servers, see how to add an MCP server to Claude Code.

Claude settings.json: where the files live

There are four places Claude Code reads settings from. Each one reaches a different set of people:

Scope File Applies to
User ~/.claude/settings.json You, in every project on this machine
Project .claude/settings.json Everyone in the repo, once you commit it
Local .claude/settings.local.json You, in this one project
Managed managed-settings.json Everyone your organization deploys it to

On Windows, ~/.claude means %USERPROFILE%\.claude. The managed file sits in a system folder: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows.

When Claude Code creates .claude/settings.local.json in a git repo, it adds the file to your global git excludes so it stays out of commits. If you create it by hand, add it to .gitignore yourself.

Claude Code settings.json precedence

When the same key is set in more than one file, the highest level wins:

  1. Managed settings
  2. Command line (--settings, for one session)
  3. Local (.claude/settings.local.json)
  4. Project (.claude/settings.json)
  5. User (~/.claude/settings.json)

Permission lists work differently. allow, ask and deny arrays from every file are merged, not replaced. And because deny is checked first, a deny in any file blocks an allow from any other file, including a higher one.

There's one more catch for teams. allow rules and additionalDirectories in a committed .claude/settings.json only apply after each person accepts the workspace trust dialog for that folder. Deny and ask rules apply straight away.

Claude Code settings you can check with /permissions

Run /permissions inside a session to open a dialog that lists every rule and the settings file it came from. You can add or remove rules there and manage working directories. To see which settings files loaded, run /status and read the Setting sources line.

Settings files are strict JSON. A comment or a trailing comma makes Claude Code report a Settings Error at the next start. Most edits, including permission changes, reload without a restart.

A starter settings.json to copy

Save this as .claude/settings.json in your project. It lets Claude run your lint and test scripts and commit without asking, prompts before any push and keeps it away from your env files:

JSON
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)",
      "WebFetch(domain:code.claude.com)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

The $schema line gives you autocomplete and validation in VS Code, Cursor and other editors that support JSON schema. Swap in your own commands, then run /permissions to check them.

Common mistakes

  • Using one slash for an absolute path. Read(/Users/alice/file) starts at the settings file's root, not the filesystem root. Use //Users/alice/file.
  • Putting * too early. Bash(git *) allows every git command, push included. Write Bash(git log *) instead.
  • Treating a Bash deny as a wall. It matches command text only. Use the sandbox for real isolation.
  • Expecting allow to beat deny. It never does, whichever file each rule lives in.
  • Setting auto or bypassPermissions as defaultMode in a project file. It's ignored there. Use user settings or the flag.
  • Relying on .claudeignore. It has no effect. Move those paths into Read deny rules.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.

FAQ

Where is the Claude Code settings.json file?

Your personal file is ~/.claude/settings.json, which applies to every project. Project files are .claude/settings.json (shared with your team) and .claude/settings.local.json (just you), both inside the project folder.

How do I give Claude Code permission to run a command without asking?

Add an allow rule such as Bash(npm run test *) to the permissions.allow list in a settings file, or add it from the /permissions dialog. Choosing "Yes, and don't ask again" on a prompt also saves an allow rule to your local settings.

Which wins, allow or deny?

Deny. Claude Code checks deny rules first, then ask, then allow, and the first match decides. An allow rule can't carve an exception out of a deny rule, even a narrower one.

Why does Claude Code still ask after I added an allow rule?

An ask rule somewhere may match the same call, since ask is checked before allow. If the rule is in a committed project file, you may not have accepted the workspace trust dialog yet. Run /permissions to see every rule and where it came from.

How do I stop Claude Code from reading my .env file?

Add Read(./.env) and Read(./.env.*) to your deny list. A Read deny rule also blocks edits and writes to the same path. Shell scripts that open files themselves aren't covered, so use the sandbox if you need a hard block.

Can I change the default permission mode?

Yes. Set permissions.defaultMode in ~/.claude/settings.json to a mode such as default, acceptEdits or plan. For one session, start with claude --permission-mode <mode>.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 310+ free guides.

Keep reading

Free AI Coding guides