The Claude Code config file, field by field

Why this file is worth understanding directly

Claude Code reads its configuration from a settings file rather than from flags you re-type every session, and most of what feels like "Claude Code's personality on this project" — which actions need confirmation, which hooks fire, which MCP servers are available — actually lives there rather than in anything you say to it in conversation. Reading a project's config file before you start working in it tells you more about how the session will behave than a few minutes of asking Claude questions about itself would.

Project scope versus personal scope

Settings can live at more than one level, and which level a given setting belongs in is itself a decision worth making deliberately rather than defaulting to wherever's most convenient at the time. A rule the whole team should follow — the project's actual permission boundaries, its shared hooks, its MCP servers — belongs committed alongside the code, so everyone gets the same behaviour and the config evolves with the project under version control. A preference specific to how one person likes to work — a broader personal allowance, a habit that doesn't generalise to teammates — belongs kept local to that person's own environment instead. Mixing the two usually produces a committed config that's either too permissive for the team's least experienced member or too restrictive for its most trusted one.

The permission fields

The permission section is where allow, ask, and deny rules for tools and paths live, and it's usually the part of the config that gets the most iteration over a project's life, since real usage surfaces gaps the original rules didn't anticipate. See configuring Claude Code permissions without fighting them for how to think about what belongs in each of those three categories — the config file is where that thinking gets written down and actually enforced, not just a place to paste defaults.

Hooks

Hook definitions in the config specify which command runs at which point in a session's lifecycle — before a tool call, after one, at session start, before Claude hands control back. A project with several hooks defined benefits from keeping each one narrowly scoped to one job rather than one large script trying to handle every case, for the same reason a large, vague function is harder to maintain than several small, specific ones: a narrow hook is easier to reason about, easier to test in isolation, and easier to debug when only one part of it needs to change.

MCP server declarations

Where a project connects to external tools and data through MCP, the server definitions — command, arguments, required environment variables — live in the config rather than being set up fresh each session. This is also where secrets management becomes a real concern: a server definition that embeds a credential directly in a committed config file leaks that credential to everyone with repository access, which is very different from a definition that reads the credential from an environment variable supplied outside the file. Prefer the latter for anything that isn't meant to be shared as widely as the codebase itself is.

Model and default behaviour settings

A project can pin defaults — which model a session starts with, what effort level to reach for absent other instruction — at the config level rather than leaving every session to inherit whatever the tool's own global default happens to be. This matters most for teams that want consistent behaviour across everyone working on the same project regardless of what each individual has set personally elsewhere; a project default overrides a personal one for work done inside that project specifically.

Reading the config before touching a new project

Before making changes in an unfamiliar codebase, it's worth reading its config file the way you'd read its README — not because you need to memorise it, but because it tells you what's already been decided about how Claude Code should behave here, which saves you from re-litigating a boundary the project already settled, or worse, working around a restriction that was put there on purpose without realising why it exists.

For the reasoning behind specific permission choices, see configuring Claude Code permissions without fighting them, and for how hooks defined here actually execute, see how Claude Code hooks actually work.