Claude Code settings, file by file

A key set at a higher level replaces the same key set lower down, with two exceptions worth knowing. Lists merge rather than override: permissions.allow from your user file and your team’s project file are combined, and a deny rule wins over an allow rule wherever either comes from. And environment variables are not a level in the stack; each variable-and-key pair has its own rule, so ANTHROPIC_MODEL exported in your shell beats the model key from any file, while an env block inside a settings file is an ordinary key that follows the levels above.

Two values are scope-limited: permissions.defaultMode of auto or bypassPermissions only takes effect from user settings, managed settings, or --settings, never from the project files a repository could commit. Files are strict JSON — a comment or a trailing comma is reported as a settings error at the next start. Claude Code watches the files and applies most edits, including permissions and hooks, to a running session. /status lists which files loaded; claude doctor lists entries it rejected.

A rule is a tool name, optionally with a pattern in parentheses. Bash(npm run *) matches any npm script; Bash(git push *) matches pushes; Read(./.env) names one file relative to the project; Edit(docs/**) matches a tree; WebFetch(domain:example.com) scopes a domain; mcp__server__tool names one MCP tool. A bare tool name such as Read matches every use. Rules from every scope are merged, deny beats allow, and an ask rule from a project or managed file outranks an allow you saved locally with “don’t ask again” — which is the usual reason a prompt keeps coming back. The syntax in full is under permission rule syntax.

A personal file is small. The $schema line gives you autocomplete and validation in any editor that understands JSON schema; the rest is preference. This one starts every session on Sonnet in plan mode, follows the stable release channel, keeps transcripts for twenty days, and lets Claude Code run git diff and read your shell config without asking.

The shared project file is the one to commit. It carries the permissions everyone should share, the environment the project needs, and hooks — shell commands Claude Code runs at fixed points, which, unlike CLAUDE.md instructions, are enforced regardless of what the model decides. The example below approves npm scripts, always confirms pushes, refuses to read secrets, and runs a script from the repository before every Bash command. Hooks nest three deep: the event, a matcher, and the handlers. Allow rules in a committed file take effect only after each person trusts the folder; deny and ask rules apply regardless.

Three things shape a session and they are easy to conflate. Settings are enforced configuration: permission rules, hooks, and the sandbox apply whatever the model intends. CLAUDE.md is instruction: loaded as context at the start of every session, followed well when it is specific, but not a hard boundary — the docs say so plainly and point you to a PreToolUse hook when something must never happen. Flags are one session’s overrides: --permission-mode beats defaultMode, --model beats model, --allowedTools and --disallowedTools add rules for the run, --add-dir grants directories without persisting them, and --settings layers a file or a JSON string above your files for the session. /config writes a few personal options to the user file, /permissions edits rules, and /hooks shows what is configured.

One practical consequence: all of this lives on the host. The user file, the project files, the transcripts, the remembered approvals — they are on the machine where claude runs, not on the device you are looking at it from. Set a machine up once and every device that reaches it gets the same sessions, the same rules, the same history. That is the shape spawnd is built around: the host does the work and keeps the state, and a browser or a phone is only ever the console.