Skip to content

Claude Code permissions in settings.json: allow, ask and deny

From the work/ 13 min read

Claude Code permissions in settings.json: what allow, ask and deny do, which file wins, and a ready-to-use rule set for a Node or Next.js project.

  • AI
  • Security
  • Claude Code
In this article (10)
  1. Approve everything or each action: Claude Code permissions and modes
  2. allow: what Claude can do without asking
  3. deny: what it must never touch
  4. ask: what always prompts you
  5. .claude/settings.json in the repo for the whole team
  6. settings.local.json: local settings that stay off git
  7. Ready-to-use examples for a Node/Next.js project
  8. Common mistakes
  9. Frequently asked questions
  10. Checklist

Claude Code permissions live in settings.json as three lists: allow (what it does without asking), ask (what always prompts you) and deny (what it can never do). Claude Code checks deny first, then ask, then allow, and the first rule that matches decides, no matter which rule is more specific.

With those three lists you can leave Claude in auto mode without worrying that it reads your .env or pushes without telling you. Below are the files we use for a Node/Next.js project, where each one goes, which file wins when two disagree, and the mistakes that make a rule do nothing. Everything was checked against the official docs on November 19, 2026.

Approve everything or each action: Claude Code permissions and modes

Before rules comes the mode. The mode decides what happens to anything no rule mentions. The permission modes documentation lists six:

ModeRuns without askingUse it for
default (Manual)Reads onlyReviewing every action
acceptEditsReads, edits and file commands such as mkdir or mv inside the projectIterating, then reviewing with git diff
planReads; no edits to your code until you approve the planExploring before changing
autoAlmost everything, reviewed by a background classifier modelLong tasks without interruptions
dontAskReads and pre-approved calls; everything else is denied without askingCI and scripts
bypassPermissionsEverythingIsolated containers or VMs only

You switch modes with Shift+Tab in the terminal, at launch with claude --permission-mode plan, or by default with permissions.defaultMode. Since version 2.1.283, auto is the mode interactive terminal and VS Code sessions start in, so plenty of people already work in auto mode without having picked it.

Auto mode is not a blank check. The classifier's default allow list includes reading .env and sending credentials to their matching API, and pushing to any branch of the repository you are working in. If you do not want that, the classifier will not stop it: your rules will. The docs are explicit on two points: deny rules block in every mode, bypassPermissions included, and ask rules still prompt in auto mode. They also warn that a boundary you state in chat ("don't push") can be lost when the conversation is compacted; for a hard guarantee, add a deny rule.

allow: what Claude can do without asking

Every rule is Tool or Tool(specifier). Bash on its own covers every command; Bash(npm run build) covers that exact command only. The asterisk stands for any text, spaces included, and these three rules from the permissions documentation explain most cases:

  • A trailing * with a space before it also matches the bare command. Bash(npm run test *) covers npm run test and npm run test -- --watch.
  • The space counts. Bash(ls *) does not cover lsof; Bash(ls*) does.
  • Put the asterisk after the subcommand. Bash(git log *) allows only git log; Bash(git *) allows every git command, push included.

The :* suffix is another way to write the trailing asterisk: Bash(ls:*) is the same as Bash(ls *). It only works at the end; in Bash(git:* push) the colon is read as literal text and the rule matches nothing useful.

Do not add to allow what already runs without asking. Claude Code ships a fixed set of read-only commands (ls, cat, grep, find, wc, diff and read-only forms of git, among others) that never prompt in any mode. And do not expect one rule to cover chained commands: with &&, ; or |, each part must be allowed on its own, so Bash(npm test) does not approve npm test && git push. On Windows, PowerShell(...) rules take the same shape.

Two more details. allow rules from a repository's .claude/settings.json apply only after you accept the workspace trust dialog for that folder. And on entering auto mode, Claude Code drops broad allow rules that grant arbitrary code execution, such as Bash(*), wildcarded interpreters (Bash(python*)) and package-manager run commands. Those commands are not blocked: the classifier reviews them instead. Narrow rules such as Bash(npm test) stay in effect, and Claude Code restores the dropped ones when you leave auto mode.

evaluation order: deny, then ask, then allowClaude's callgit push origin mainone command, three listsalways checked in this orderdenyBash(git push --force *)on a match: blockedgit push origin main does not match: on to askaskBash(git push *)match: you are askeddecided here: the first match winsallowBash(git push origin main)more specific, too latenever reached: ask already decidedif no rule matches, the permission mode decidesspecificity does not win: the order doessource: Claude Code permissions documentation

Scroll the figure sideways to see all of it

deny: what it must never touch

To stop Claude reading a file, put a Read rule in deny. Paths use .gitignore syntax: Read(.env) and Read(**/.env) are equivalent and block any .env inside the project, at any depth. A Read deny also blocks Edit and Write on that path, so Claude cannot create or overwrite the file either. The rule reaches the file commands Claude Code recognizes in the shell, such as cat, head or sed, and redirections such as < .env.

Where a path starts depends on how you write it:

  • ~/path starts at your home folder: Read(~/.ssh/**).
  • //path is absolute from the filesystem root. On Windows, C:\Users\you is read as /c/Users/you.
  • /path, with one slash, is not absolute: it starts at the settings file's location. In the project that is the project root; in ~/.claude/settings.json it is ~/.claude.
  • A rule starting with ! carves paths out of the earlier rules in the same file: Read(!.env.example) after Read(**/.env.*) lets Claude read the template.

Now the limits, because a deny rule is not a wall. A Bash rule compares the command text as Claude writes it: Bash(curl *) stops curl https://example.com but not /usr/bin/curl or sh -c 'curl ...'. And a Read deny does not reach grep -r key . or a Node script that opens the file itself. For OS-level blocking the docs recommend the sandbox; to inspect every command with your own logic, a PreToolUse hook, which is what we built in the hook that protects your .env. Both add to the rules; neither replaces them.

If the secret lives in a NEXT_PUBLIC_ variable, no rule protects it: it is already in the JavaScript the browser downloads. We cover that in NEXT_PUBLIC_ variables and secrets.

ask: what always prompts you

ask is the list that makes auto mode calm. Per the settings reference, an ask rule prompts you even in a mode that would otherwise approve the call, such as acceptEdits or bypassPermissions, and in auto mode an ask rule does not go to the classifier: it comes to you. In dontAsk, with nobody to ask, the call is denied.

ask and deny rules apply to any part of a chained command, even inside a subshell or a command substitution: with Bash(git push *) in ask, npm test && git push prompts too. Use it for what leaves your machine or is hard to undo: git push, adding or removing dependencies, deleting files, network requests with curl.

Order matters here more than anywhere. Because deny is checked before ask, you can put Bash(git push --force *) in deny and Bash(git push *) in ask: a push with --force up front is blocked and a normal push prompts. And because ask is checked before allow, a more specific allow rule will not skip the prompt.

.claude/settings.json in the repo for the whole team

Claude Code reads four files and, if your organization sets it up, a managed one. The settings documentation ranks them, highest first:

  1. Managed (managed-settings.json, MDM or the claude.ai console): nothing below changes it.
  2. Command line: claude --settings <file or JSON>, for that session only.
  3. Project local: .claude/settings.local.json.
  4. Shared project: .claude/settings.json.
  5. User: ~/.claude/settings.json.

That order decides when a single value, such as defaultMode, appears in two files. Lists work differently: allow, ask and deny merge across files, and a deny at any level blocks even if another file allows it. If your user file allows something and the project file denies it, the deny wins; the reverse holds too.

settings files: the one higher up wins1 managedmanaged-settings.json, MDM or consoleset by your organization; nothing below changes it2 command lineclaude --settings <file or JSON>for that session only3 project local.claude/settings.local.jsononly you, in this project; kept out of git4 shared project.claude/settings.jsoncommitted for the whole team; allow waits for trust5 user~/.claude/settings.jsonyou, in every projectallow, ask and deny lists add upa deny in any file blocks, even if another file allows it

Scroll the figure sideways to see all of it

.claude/settings.json goes into git so the whole team gets the same rules. Three things to know before you commit it:

  • Its deny and ask rules apply right away; its allow rules wait until each person trusts the folder.
  • "defaultMode": "auto" and "bypassPermissions" have no effect from this file or the local one. To start in auto, set it in ~/.claude/settings.json.
  • It is strict JSON: a // comment or a trailing comma breaks the file and Claude Code reports a Settings Error. The $schema line gives you autocomplete in your editor.

To see what loaded, use /permissions, which lists every rule with the file it comes from, and /status, whose Setting sources line names the files that were read. claude doctor shows the entries Claude Code rejected.

settings.local.json: local settings that stay off git

.claude/settings.local.json is yours: it applies only to you, only in that project, and ranks above the shared file. When you pick "Yes, and don't ask again" on a Bash prompt, Claude Code saves the allow rule there, at the repository root; on Windows, outside a repository or when the root is your home folder, it saves it next to .claude/settings.json. The first time it writes the file, Claude Code adds **/.claude/settings.local.json to your global git excludes. If you create it by hand, add it to .gitignore yourself: if git tracks it, Claude Code treats it as a repository file and its allow rules wait for folder trust.

It is the place for rules that only make sense on your machine, such as an MCP server you registered just for yourself. In the read-only Postgres MCP server we called it postgres-ro; its tools are written mcp__postgres-ro__*. mcp__ rules take no parentheses: add one and Claude Code skips the rule when it loads the file.

One detail that trips people up: an allow rule in your local file does not beat an ask rule from the project or your organization. If you answered "don't ask again" and it still prompts, someone has an ask rule that covers that command.

Ready-to-use examples for a Node/Next.js project

This is the .claude/settings.json we suggest for an npm project. Validated against Claude Code's published schema:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm run build)",
      "Bash(npm test)",
      "Bash(npm run test *)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(npm install *)",
      "Bash(npm i *)",
      "Bash(rm *)",
      "Bash(curl *)"
    ],
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(!.env.example)",
      "Read(secrets/**)",
      "Read(**/*.pem)",
      "Bash(git push --force *)",
      "Bash(npm publish *)"
    ]
  }
}
  1. $schema turns on autocomplete; the schema checks the file's shape, not whether a rule makes sense.
  2. The first four allow rules are exact commands: they take no extra arguments. Swap the names for the scripts in your package.json.
  3. Bash(npm run test *) covers npm run test and its arguments, but not npm run test:e2e, because the space is part of the rule. If you have that script, add it separately.
  4. git commit and git push sit in ask: you see the message and the branch before they go out.
  5. npm install and npm i are separate rules: Bash rules compare text and know nothing about aliases.
  6. rm and curl prompt instead of being blocked, because deleting .next or hitting localhost are normal tasks.
  7. Read(**/.env) and Read(**/.env.*) block .env, .env.local and .env.production at any depth; Read(!.env.example) lets Claude read the template, which holds no real values.
  8. Read(secrets/**), as a deny rule, blocks any secrets folder in the project; Read(**/*.pem) covers keys and certificates.
  9. git push --force is in deny even though git push is in ask: deny is checked first.
  10. npm publish is in deny because a published version cannot be replaced.
rules for a Node/Next.js projectlistrulewhyallowBash(npm run lint)that exact command onlyallowBash(npm run test *)test with any argumentsaskBash(git push *)auto mode would push; you decideaskBash(npm install *)a new dependencyaskBash(rm *)deleting filesdenyRead(**/.env)also blocks Edit and Write theredenyRead(**/.env.*).env.local, .env.productiondenyBash(npm publish *)a publish cannot be undonedaily work in allow, what leaves in asksecrets and what cannot be undone in deny

Scroll the figure sideways to see all of it

For your machine, in ~/.claude/settings.json, block what lives outside your projects. Note the ~/: with a single /, the rule would point at ~/.claude.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.npmrc)"
    ]
  }
}

If you would rather start in auto mode, swap acceptEdits for auto in this file: it is the only one of yours where that value takes effect. The guide includes check-permissions.mjs, a dependency-free Node script that checks your files for the mistakes in this article. This is its output on the files above and on a test project we wrote with deliberate mistakes:

$ node check-permissions.mjs .claude/settings.json .claude/settings.local.json
OK   .claude/settings.json
OK   .claude/settings.local.json

$ node check-permissions.mjs .claude/settings.json .claude/settings.local.json
FAIL .claude/settings.json
     - allow: Bash approves any program
     - allow: Bash(git:* push) has ":*" before the end, where the colon is literal
     - allow: mcp__github__get_issue(owner:acme) is skipped: mcp__ rules take no parentheses in a settings file
     - deny: Write(.env) never matches a path; write Edit(...) or Read(...)
     - deny: Grep(secrets/**) never matches a path; write Edit(...) or Read(...)
     - defaultMode "auto" has no effect in a project or local file
     - no Read deny rule for .env files
FAIL .claude/settings.local.json
     - not valid JSON (no comments, no trailing commas): Expected property name or '}' in JSON at position 4 (line 2 column 3)

The official schema accepted that broken file without complaint: it checks that each rule looks like a rule, not that it does what you think. The script does not replace Claude Code; it only flags traps the documentation describes.

Common mistakes

  • Thinking the most specific rule wins. Order wins: deny, ask, allow. An allow cannot carve a hole in a deny.
  • Setting "defaultMode": "auto" in the repository. It has no effect from .claude/settings.json or the local file; put it in ~/.claude/settings.json.
  • Write(.env) or Grep(secrets/**). Write, Glob and Grep rules with a path never match; use Edit(...) or Read(...).
  • /secrets/** in your user file. A single slash points at ~/.claude/secrets; use ~/ or //.
  • Treating a Bash rule as a security boundary. /usr/bin/curl and sh -c get around it; that is what the sandbox is for.
  • Comments in the JSON. They break the whole file; explain the rules in the README or the commit message.
  • Committing settings.local.json. Your rules become the repository's and wait for each person's trust.

Frequently asked questions

Do deny rules work in auto mode and bypassPermissions?

Yes. The docs say deny blocks in every mode, bypassPermissions included. What stops applying in bypassPermissions is allow rules, since everything is already allowed.

Why does it still prompt after I picked "Yes, and don't ask again"?

That answer saves an allow rule in your local file, and an allow never beats an ask. Open /permissions to find the ask rule that covers the command and the file it comes from.

Do I need rules if I already use auto mode?

Yes, if something must never happen. By default the classifier allows reading .env and pushing to your repository, and what you tell it in chat can be lost when the conversation is compacted. Rules live in a file and do not depend on context.

Permission rules or a hook?

Rules first: they are declarative and easy to review in a diff. A PreToolUse hook is for when you need logic, such as inspecting the full text of a command; a hook that exits with code 2 blocks before the rules are checked.

Checklist

  • .claude/settings.json in git with $schema and all three lists.
  • allow holds only exact commands or rules with the asterisk after the subcommand.
  • ask covers pushes, commits, dependencies, deletions and network calls.
  • deny covers .env, .env.*, keys and anything that cannot be undone.
  • .claude/settings.local.json stays out of git.
  • defaultMode set to auto, if you want it, only in ~/.claude/settings.json.
  • User paths use ~/ or //, never a single /.
  • /permissions and /status show what you expect.
  • You asked Claude to read .env and it refused.

Saw this on Instagram? Comment PERMISOS on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026

← Blog