settings.json — Permissions allowlist

What it does

Every Claude Code tool call prompts for permission by default. The settings.json permissions allowlist preapproves specific commands so you skip the permission dialog for safe, repetitive operations. Instead of approving "run npm ci" ten times a day, you approve it once in settings and the prompt vanishes — but you retain full control by scoping approval to specific commands, file paths, or permission modes.

Permissions have three layers: global (affects all projects), project (in .claude/settings.json, checked into your repo), and local (in .claude/settings.local.json, gitignored). Scopes nest, so a project allowlist overrides global. Denials always win — if global allows npm install but project denies it, the command is blocked.

When to use it

Use allowlists to suppress permission prompts for commands you audit once and trust repeatedly: npm ci, git status, git log, find . -name "*.ts", or MCP tool calls like read and grep. The /fewer-permission-prompts skill scans your recent transcript and auto-generates an allowlist of the most common safe calls.

Project-level allowlists (.claude/settings.json) are most useful because they encode what this codebase needs — every developer on the team benefits, and the rules are version-controlled. Global allowlists are right for your personal CLI defaults that apply everywhere (e.g., always allow git status).

Scoping is critical: an allowlist that says "allow all bash commands" defeats the purpose. Always be specific: allow npm ci (reproducible install), not npm (could run anything).

Try it yourself

Check your recent transcript for the permission prompts you've approved most. The /fewer-permission-prompts skill will scan those and draft an allowlist tailored to your workflow — save it to .claude/settings.json in the project so your teammates benefit too. You can also hand-edit settings.json with specific tools like read, bash:git, or MCP endpoints you use constantly.

Gotchas

Allowlist syntax is strict. A misspelled command name or tool path won't block — it just fails silently, and the prompt reappears. Use grep on your settings file after editing to verify the command names match what Claude Code expects.

Denials are irrevocable within that scope. If you deny a command in project settings, global settings can't override it. Only remove the deny entry or escalate to a less-specific scope.

NEXT_PUBLIC env vars aren't secrets. Allowing bash doesn't let you read .env files — the harness sandboxes filesystem access separately. But be cautious approving commands that write or delete files; read-only operations like git log or find are safer to auto-approve.

Permissions don't stack across tool types. Approving bash:npm doesn't auto-approve read on package.json. Each tool category has its own permission scope, so an allowlist is granular by design — you're trading friction for safety, not just speed.