Claude Code permissions · practical guide

Treat permissions as repository policy, not prompt cleanup.

The best starting profile allows repeatable local verification, asks before side effects, and denies a small number of operations the repository never wants an agent to perform.

Put shared policy in the shared scope

Anthropic documents current scope and precedence behavior in the official settings reference.

Use deny, ask, and allow for different jobs

• Deny: operations and paths the agent should not access in this workflow.
• Ask: legitimate but side-effecting operations that deserve a human decision.
• Allow: exact, routine commands the team expects on most changes.

Current Claude Code rule evaluation gives deny rules priority, followed by ask and allow. Rules are tool-specific: denying the Read tool for .env does not magically make every possible shell program unable to read it. Pair rules with narrow Bash access, sandboxing, and credentials that have the minimum external authority.

A deliberately small starter profile

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

Adapt this to the repository’s real package manager, test commands, protected files, and release process. Remove rules for tools the project does not use. Prefer a short reviewed policy over an enormous copied allowlist.

Choose a mode from the environment

• default: a sensible first-week baseline for an unfamiliar or sensitive repository.
• acceptEdits: useful when local edits are routine and you are actively reviewing them.
• plan: useful for exploration before changing source files.
• dontAsk: useful for locked-down automation where everything not pre-approved should fail closed.
• bypassPermissions: reserve for genuinely isolated disposable environments; it skips ordinary permission prompts.

Modes and fields can change. Verify the current behavior in Anthropic’s permissions documentation before rolling a profile out broadly.

A five-minute permission review

1. List commands used for test, lint, typecheck, and build.
2. List external side effects: pushes, releases, cloud mutations, messages, and package publication.
3. List credentials and local paths the workflow does not need.
4. Allow the first list narrowly, ask on legitimate side effects, and deny irrelevant high-impact operations.
5. Trigger one allow, ask, and deny case in a disposable branch or fixture.