Claude Code settings.json: Permission Rules That Keep an Agent Safe

Published 2026-10-16 · 4 min read · by AgentKit Co

CLAUDE.md tells Claude Code how your project works. settings.json decides what it is allowed to do. The difference matters: the official docs say permission rules are enforced by Claude Code itself, not by the model, while instructions in CLAUDE.md only shape what Claude tries. If a line must never be broken ("never read .env", "never push"), it belongs in a permission rule, not only in prose.

This guide covers the four settings files, which one wins, how the rules match, and a starter file. It was checked against Anthropic's settings and permissions pages on 2026-10-16. Claude Code changes quickly, so re-check the docs for anything you rely on.

The four files and who they affect

Installing Claude Code does not create any of these. When you choose "Yes, and don't ask again" on a permission prompt, Claude Code saves that approval as an allow rule in .claude/settings.local.json. If you create that file by hand, add it to .gitignore yourself.

Which value wins

For a single key, the highest level that sets it wins: managed settings, then --settings on the command line, then project local, then shared project, then user. Lists are different. permissions.allow and the other rule lists merge across files, so each file adds rules instead of replacing another file's.

How allow, ask and deny work

• allow: run without asking.
• ask: always prompt.
• deny: block.

Rules are evaluated deny first, then ask, then allow, and the first match in that order decides. A more specific rule does not change the order: a broad deny such as Bash(aws *) blocks aws s3 ls even if you also allow Bash(aws s3 ls). You cannot carve an exception out of a deny rule with an allow rule.

Wildcards, briefly

A * in a Bash rule matches any text, including spaces. Put it after the subcommand so the words before it limit the rule:

• Bash(npm run *) matches npm run build and npm run test --watch, not npm install.
• Bash(git log *) allows only git log commands; Bash(git *) allows every git command.
• Bash(ls *) needs a space after ls, so it does not match lsof. Bash(ls*) does.

The docs also note what a Bash rule does not catch: a deny for Bash(git push *) does not match a push written another way, such as git -C . push. Treat deny rules as a strong guard rail, not a sandbox.

A starter project file

Settings files are strict JSON, so no comments and no trailing commas. Adjust the commands to your project before committing it as .claude/settings.json:

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

The $schema line gives autocomplete and validation in editors that support JSON schema. After saving, run /status inside Claude Code to confirm which settings files loaded, and claude doctor to see any entries it rejected.

Three checks before you commit it

1. Commit only what the team agrees on. Personal approvals belong in .claude/settings.local.json.
2. Know that team allow rules wait for trust. The docs say permissions.allow rules in a committed file apply only after each teammate trusts the folder, while deny and ask rules apply right away.
3. Keep the prose and the rules consistent. If CLAUDE.md says "ask before installing packages", add the matching ask rule so the two never disagree.

Pair it with a good CLAUDE.md

Permissions stop the dangerous actions; the instruction file makes the everyday ones right. Our guide on AGENTS.md vs CLAUDE.md vs Cursor rules explains which file each tool reads, and the free AGENTS.md generator builds a starting file in a minute.

AgentKit Co is not affiliated with Anthropic. This is an independent guide written with AI assistance and checked against the linked documentation.

Keep reading