Configuring Claude Code: settings.json, CLAUDE.md & Permissions

If you have ever wondered where claude code settings actually live, you are not alone. Claude Code spreads its configuration across a handful of files and directories rather than one giant config blob, and once you understand the map it becomes easy to reason about. This guide gives you a conceptual overview of the whole configuration surface: the settings.json hierarchy, CLAUDE.md memory files, the permission system, hooks, and the custom commands and agents that live under .claude/. For exact key names and the latest syntax, always defer to the official Claude Code docs — the tool moves fast, and this is a map, not a spec. Claude Drops is an independent project and is not affiliated with Anthropic.

The shape of Claude Code configuration

Claude Code is configured through three broad mechanisms, and keeping them mentally separate saves a lot of confusion. First, there is structured configuration in settings.json — things like permissions, environment variables, and the model to use. Second, there is context in CLAUDE.md files (often called memory) — natural-language instructions that get loaded into Claude's context automatically. Third, there is everything under the .claude/ directory — custom slash commands, subagents, hooks, and skills that extend what Claude can do. Knowing which mechanism owns which concern is the key to configuring Claude Code well.

settings.json: user vs project vs local

The settings.json file is where the structured claude code settings live, and there are several layers that cascade. Understanding the layering matters because more specific scopes override broader ones, while an enterprise-managed policy sits above everything and cannot be overridden. Conceptually the layers are: a user-level file in your home directory, a project-level file checked into the repo, a project-local file that stays out of version control, and an organization-managed policy file that administrators can deploy. Command-line arguments also factor into precedence. The exact paths and the precise order are documented — check the docs before relying on a specific override winning.

Common things you will set in settings.json include the permissions block (covered below), an env map for environment variables passed to the session, hooks for automation, and the model to use. Because the project file is committed, it is the natural home for conventions you want the whole team to inherit; the local file is where you keep machine-specific tweaks. If you are not sure which file a setting belongs in, ask whether it should travel with the repo — that answer usually decides it.

CLAUDE.md and memory

Where settings.json is structured config, CLAUDE.md is free-form context that Claude reads automatically when a session launches. This is how you teach Claude about your codebase: the build and test commands, naming conventions, architectural boundaries, libraries you prefer, and things you want it to avoid. Like settings, memory files exist at multiple scopes — a user-level file at ~/.claude/CLAUDE.md that applies everywhere, a project-level CLAUDE.md at the repo root that travels with the code, and an enterprise policy memory that administrators can manage. Many teams also keep memory files in subdirectories so Claude picks up area-specific guidance as it works.

A few practical habits make memory far more effective. Keep it concise — it consumes context window on every turn, so bullet points beat essays. Treat it as living documentation that you refine when Claude repeatedly gets something wrong. And use imports to keep things modular: a CLAUDE.md can reference other files with an @path import so you can split conventions into focused, reusable pieces rather than one sprawling document. The exact import rules and the full list of memory locations are in the docs; the concept to internalize is that memory is your highest-leverage configuration knob for steering behavior.

• Project conventions: how to run tests, lint, build, and deploy
• Architecture notes: module boundaries, where things live, what not to touch
• Style preferences: libraries, patterns, formatting choices the team agrees on
• Gotchas: known footguns, flaky areas, or commands that must never run

Permissions and allowlists

Permissions control what Claude can do without stopping to ask you, and they are one of the most important claude code settings to get right. The permission system is rule-based with three outcomes: you can allow certain actions to run automatically, ask for confirmation, and deny others outright. Rules are expressed as tool patterns — for example Bash(npm run build) for a specific command, or path-scoped rules like Edit(docs/**) — so you can permit a class of read-only actions while still requiring confirmation for anything that writes or deletes. Deny rules act as hard guardrails and take precedence over allow rules, which makes them ideal for blocking dangerous operations regardless of what else is allowed.

Because permission rules live in settings.json, they follow the same user/project/enterprise layering. That means a team can ship a sensible project allowlist in the committed settings file, individuals can loosen or tighten things in their local file, and an organization can enforce non-negotiable guardrails from the top. The smart default is to start restrictive and widen the allowlist as you build trust in specific commands. For the exact rule syntax — how tool names, command patterns, and arguments are matched — consult the permissions section of the docs rather than guessing at the format.

Hooks: automation around the loop

Hooks let you run your own commands at defined points in Claude's lifecycle — before or after a tool runs, when a session starts, and so on. They are configured in settings.json and are how you wire deterministic automation into the agentic loop: auto-formatting files after edits, running a linter before a commit, blocking a tool call that violates a policy, or sending a notification when a long task finishes. Hooks shift behavior from "Claude usually remembers to" into "this always happens," which is exactly what you want for guarantees. We go deeper in our guide to Claude Code hooks.

The .claude directory: commands, agents, and skills

Beyond settings and memory, the .claude/ directory is where you extend Claude with new capabilities. Custom slash commands are reusable prompts you invoke by name — see our slash commands guide for how to author them. Subagents are specialized assistants with their own instructions and tool access that the main agent can delegate to; we cover them in the subagents explainer. And these definitions follow the same scoping idea as everything else — keep them in a user-level directory to make them available everywhere, or commit them under the project so the whole team gets them.

Two related extension points round out the picture. MCP servers connect Claude to external tools and data sources through the Model Context Protocol; the MCP overview walks through how that plumbing works. And skills package up procedural know-how that Claude loads on demand. The mental model is consistent across all of them: a directory of definitions, scoped at the user or project level, that the docs describe in precise detail. If you are still getting oriented, what is Claude Code is a good starting point, and the glossary defines the terms used throughout.

~/.claude/
  settings.json        # personal, all projects
  CLAUDE.md            # personal memory
  commands/            # personal slash commands
  agents/              # personal subagents

<repo>/.claude/
  settings.json        # shared, committed
  settings.local.json  # personal, gitignored
  commands/            # project slash commands
  agents/              # project subagents
<repo>/CLAUDE.md       # project memory

Putting it together

A healthy configuration usually looks like this: a committed project CLAUDE.md that captures conventions, a committed .claude/settings.json with a conservative permission allowlist and a few useful hooks, a personal settings.local.json for machine-specific tweaks, and a small set of custom commands and agents for repetitive workflows. Start minimal and add configuration only when you feel friction — over-configuring early tends to create more confusion than it removes. As Claude Code evolves, new keys and capabilities land regularly, which is exactly why it pays to keep an eye on releases.

That is the configuration map. When you need the exact key names, permission rule grammar, or hook event names, go straight to the source — and to stay current as new options ship, watch the Claude Code changelog or check the latest release. Claude Drops exists to make that easy: it tracks every Claude Code release so configuration changes never catch you off guard.