.claude/settings.json

.claude/settings.json is the machine-readable configuration file for Claude Code. Where CLAUDE.md provides natural-language context and instructions, settings.json controls *behavioral* configuration: what tools Claude Code is allowed to use, what hooks run at lifecycle points, environment variables, and other structured settings.

Scope and location:

• Project-scoped: .claude/settings.json at the project root. Checked into version control — all developers on the project share the same permissions and hooks.
• User-scoped: ~/.claude/settings.json for personal preferences that should not be committed (e.g., personal API keys, preferred editor integrations).

Like CLAUDE.md, the two scopes compose. User settings layer on top of project settings.

Key configuration areas:

*Tool permissions* — which built-in tools (Read, Write, Bash, etc.) Claude Code may use without prompting. You can allowlist specific tools, restrict to read-only, or require approval for destructive operations.

*Hooks* — shell commands to run at lifecycle events: PreToolUse, PostToolUse, Stop, SubagentStop. The hooks array in settings.json is the authoritative place to define them.

*Environment variables* — values injected into every session, useful for setting NODE_ENV, pointing to local services, or propagating non-secret configuration.

A minimal settings.json looks like:

{
  "permissions": {
    "allow": ["Read", "Write", "Bash"],
    "deny": []
  },
  "hooks": {
    "PostToolUse": ["npm test"]
  }
}

The distinction between settings.json and CLAUDE.md is important: CLAUDE.md is for humans and Claude to read (context, reasoning, conventions); settings.json is for the harness to execute (permissions, scripts, structured config). Getting this wrong — for example, putting hook commands in CLAUDE.md — is a common trap that produces instructions Claude can read but the harness cannot act on.

See also: CLAUDE.md, Hooks (Claude Code).

Related concept: CLAUDE.md Configuration Hierarchy.

Scenario questions typically present a situation and ask whether the solution belongs in CLAUDE.md, project settings.json, or user settings.json:

• "Enforce that Claude Code never executes rm -rf for any developer" → project settings.json (tool deny list, shared)
• "Set a personal preference for verbose output" → user ~/.claude/settings.json
• "Explain the project's microservice architecture to Claude" → CLAUDE.md (natural language context, not machine config)

Hook placement is another tested distinction: hooks are defined in settings.json, even though the hook *scripts* might be referenced from anywhere.