settings.json is the primary configuration file for Claude Code. It's a plain JSON file that controls how the tool behaves — defining things like tool permissions, environment variables, hooks, and other preferences — without you having to pass flags on every run.
Claude Code reads settings from several layers that merge together, with more specific layers winning. From lowest to highest precedence: a user-level file in your home directory (~/.claude/settings.json) that applies across all your projects, a project-level file checked into the repo (.claude/settings.json) that is shared with your team, and a local override (.claude/settings.local.json) that's personal and typically git-ignored. Enterprise managed settings sit above all of these and can't be overridden.
You can edit the file by hand or use the /config command to open Claude Code's interactive settings interface. Because the exact set of supported keys evolves as Claude Code ships updates, check the official Claude Code documentation for the current schema rather than relying on memory. settings.json is distinct from CLAUDE.md, which holds natural-language project memory and instructions rather than structured configuration.
Why it matters
settings.json is where you make Claude Code work the way you want — pre-approving safe tools to cut down on permission prompts, wiring up hooks to automate checks, and sharing a consistent setup with your team by committing the project-level file. Understanding the user / project / local / managed layering lets you keep personal tweaks separate from team-wide standards.
Related terms
See settings.json in action across releases — browse the Claude Code changelog.
Get release alerts