Claude Code settings.json Builder

Claude Code settings.json — the complete reference

settings.json is Claude Code's configuration file. It controls what Claude is allowed to do without asking (permissions), the environment it runs in (env), which model it uses, and what happens at lifecycle events (hooks). It's plain JSON — no build step, no CLI wizard required — which is why a generator like the one above is all you need.

Three files, three scopes

The same schema lives at three paths, and which one you edit decides who it applies to:

Precedence: who wins when settings conflict

More specific beats more general. From highest priority to lowest:

1. Enterprise managed policies — deployed by an IT admin (managed-settings.json in the system directory); users can't override these
2. Command-line arguments — per-session flags like --model
3. Local project settings — .claude/settings.local.json
4. Shared project settings — .claude/settings.json
5. User settings — ~/.claude/settings.json

For permissions specifically, rules from every file are merged — and a deny rule wins over an allow rule regardless of which file it comes from. You can allow Bash broadly in your user settings and a project's deny list will still block Bash(curl:*).

The permissions block

This is the block most people come here for. Five keys matter:

"permissions": {
  "allow": [ "Bash(npm run test:*)" ],
  "ask":   [ "Bash(git push:*)" ],
  "deny":  [ "Read(./.env)", "WebFetch" ],
  "additionalDirectories": [ "../docs/" ],
  "defaultMode": "acceptEdits"
}

• allow — matching tool calls run without a prompt.
• ask — matching calls always prompt for confirmation, even when a broader allow rule matches.
• deny — matching calls are blocked outright. Deny beats allow and ask. This is also the mechanism for keeping files away from Claude entirely: a Read deny rule stops the file being read at all.
• additionalDirectories — extra directories (beyond the working directory) Claude may access.
• defaultMode — the permission mode a session starts in: default (prompt on first use of each tool), acceptEdits (auto-accept file edits), plan (read-only), or bypassPermissions (no prompts at all — sandboxed containers only). Two more exist for narrower cases: dontAsk (auto-deny anything not pre-approved) and auto (auto-approve with background safety checks — a research preview).

Permission rule syntax

Every rule is either a bare tool name (WebFetch matches every use of the tool) or a tool name with a specifier: Tool(specifier). The specifier's meaning depends on the tool:

Bash rule gotchas

• Bash(git diff:*) allows git diff HEAD~1 but a plain Bash(git diff) allows only the two-word command, exactly.
• Prefix matching is text matching, not shell parsing. Claude Code is aware of chaining — safe-cmd && scary-cmd doesn't sneak through an allow rule for safe-cmd — but options still count as prefix text: Bash(npm run test:*) also matches npm run test -- --dangerous-flag.
• Prefer allowing narrow, specific scripts (npm run lint) over broad runners (npm:*).

Read/Edit path forms

Read and Edit rules follow the gitignore spec, with four ways to anchor a path:

The single leading slash is the one that surprises people: Edit(/src/**) is not an absolute path — it's relative to wherever the settings file lives. Use // when you really mean the filesystem root.

Common recipes

A sensible project baseline

"permissions": {
  "allow": [
    "Bash(npm run test:*)",
    "Bash(npm run lint:*)",
    "Bash(git diff:*)",
    "Bash(git log:*)"
  ],
  "ask": [ "Bash(git push:*)" ],
  "deny": [
    "Read(./.env)",
    "Read(./.env.*)",
    "Read(./secrets/**)"
  ]
}

Lock down network access

"permissions": {
  "allow": [ "WebFetch(domain:docs.anthropic.com)" ],
  "deny":  [ "WebFetch", "Bash(curl:*)", "Bash(wget:*)" ]
}

Deny beats allow — so this blocks all fetching except the allowed domain? No: a bare WebFetch deny blocks everything, including the allow rule. To allowlist domains, deny nothing and allow only the domains you want; unlisted domains then fall back to prompting. Keep the curl/wget denies either way — shell commands are the classic way around a WebFetch rule.

Environment variables

Everything under "env" is applied to every Claude Code session. Useful ones:

All values must be strings — the builder above quotes them for you.

Hooks

Hooks run your own shell commands at lifecycle events — before a tool call (PreToolUse), after one (PostToolUse), when Claude finishes responding (Stop), and more. They live under the "hooks" key of this same file. Designing matchers and commands is its own topic — use the Hooks Builder, which walks through every event and emits a fragment you can paste into the Hooks field above to merge into your full settings.json.

Top-level key reference

FAQ

settings.json or CLAUDE.md — which one do I want?

settings.json configures the tool: hard rules the software enforces (permissions, env, hooks). CLAUDE.md instructs the model: conventions and context it reads as prose. A deny rule in settings.json is enforced; a "please don't" in CLAUDE.md is a request.

Do I need to restart Claude Code after editing?

Start a new session to be sure. Settings are read at session start; a running session won't reliably pick up edits.

Where do MCP servers go — settings.json?

Server definitions live in .mcp.json (project) or via claude mcp add. settings.json only controls approval of those servers (enableAllProjectMcpServers and friends) and per-tool permission rules (mcp__server__tool).

My allow rule isn't working.

Three usual suspects: a deny rule somewhere in the stack (deny always wins, check all three files plus managed policies), a missing :* on a Bash rule you meant as a prefix, or a Read/Edit path anchored to the wrong base — remember /path is settings-file-relative, not absolute.

Is it safe to commit .claude/settings.json?

Yes — that's the point of the project scope. Keep personal machine paths and experiments in settings.local.json, which Claude Code adds to .gitignore automatically.