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
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:
{
"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 namedgithubmcp__github__get_*matches its tools that start withget_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:
- Managed settings
- Command line (
--settings, for one session) - Local (
.claude/settings.local.json) - Project (
.claude/settings.json) - 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:
{
"$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. WriteBash(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
autoorbypassPermissionsasdefaultModein a project file. It's ignored there. Use user settings or the flag. - Relying on
.claudeignore. It has no effect. Move those paths intoReaddeny 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>.