7 hidden Claude Code settings that change everything
Claude Code reads plain JSON settings files — and a few keys inside them quietly decide how much Claude asks before acting, what your terminal shows, which model every session starts on, and when your context gets compacted. Here are seven of them, with the exact JSON, where each one belongs, and when you’d actually use it.
Explain it like I’m five
Think of Claude Code’s settings like the rules of a shared apartment. Your own house rules follow you to every room — that’s your personal settings. Your roommate writes rules on the fridge for everyone in the apartment — that’s the project’s shared settings. You stick a note on your own bedroom door that only applies to your room — that’s your project-local settings. And the landlord’s lease sits on top of everything: nothing you write can overrule it.
When two rules disagree, the higher one wins: the landlord over you, you over your roommate. This guide is about seven little keys hiding inside those files that most people never touch — and how flipping them quietly reshapes how Claude Code behaves for you: how much it asks, what it shows, which brain it starts with, and when it tidies up its memory.
First, the map: four files, one pecking order
Claude Code reads its settings from four files. Which file a setting lives in decides who it applies to — and which file wins when two of them disagree.
- Your settings, ~/.claude/settings.json — you, in every project on this machine. Personal preferences live here.
- Shared project settings, .claude/settings.json — everyone working in that project folder. Commit it so your teammates get the same rules.
- Project local settings, .claude/settings.local.json — you, in this one project only. Claude Code keeps it out of git when it creates the file; if you create it by hand, add it to .gitignore yourself.
- Managed settings — deployed by your organization (a file, an MDM policy, or the admin console). Nothing you set overrides these.
When the same key appears in more than one place, the winner is the highest level that sets it, in this order: managed > command line (--settings, one session only) > project local > shared project > user. So your project-local file beats the team’s shared file, and the organization’s managed settings beat everything you do.
Settings files are strict JSON: a // comment or a trailing comma is a syntax error, and Claude Code reports the file as a Settings Error at the next start. To see what actually loaded, run /status inside Claude Code — its Setting sources line lists the files it read. To see which entries it rejected, run claude doctor.
1 · Pick how much Claude asks: permissions.defaultMode
This is the dial for Claude Code’s caution. It decides which permission mode every new session starts in — that is, how often Claude stops to ask “can I do this?” before acting.
The values read like a sliding scale. “default” runs only reads without asking. “acceptEdits” also runs file edits and everyday filesystem commands like mkdir without asking. “plan” reads and plans but blocks edits until you approve the plan. “auto” runs without routine prompts — before bigger actions such as shell commands, a background classifier checks they line up with your request. “bypassPermissions” runs everything without asking; it’s the setting behind the --dangerously-skip-permissions flag.
“auto” and “bypassPermissions” don’t take effect from project or local settings — a repository you clone can’t quietly grant itself that power. Put those two values in your user settings (~/.claude/settings.json) instead, or pass --permission-mode for a single session.
{
"permissions": {
"defaultMode": "auto"
}
}You’re a solo developer on your own side project, and you’ve noticed you approve nearly every prompt anyway. Setting defaultMode to “auto” in your user settings makes every new session start in flow: routine work runs without the stop-and-ask, and your deny rules still block in every mode, including bypass. On the other hand, opening an unfamiliar repo? Flip it to “plan” for that project and Claude proposes before it touches anything.
One key is the difference between “may I?” every thirty seconds and a partner that just gets on with it.
Source: Anthropic docs — settings reference, permissions.defaultMode ↗2 · Your own tripwires: hooks
Hooks let you run your own commands at moments in Claude Code’s lifecycle — for example, right before a tool call happens. Your script gets to look at what’s about to run and weigh in.
Each hook is attached to an event, has a matcher for when it fires, and runs a handler — a shell command, a prompt, an agent, an HTTP request, or an MCP tool. Handlers you define in different settings files merge together rather than replacing each other, so the team’s hooks and yours can coexist.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/block-secret-commit.sh" }
]
}
]
}
}A hook on the pre-tool-call event that inspects the command about to run and stops it if it looks like a commit carrying secret files — say, a .env or .pem file — so credentials never leave your machine by accident. It’s a guardrail you set once and forget: the script runs silently on every command, and only speaks up when something risky is about to happen.
Hooks turn Claude Code from a fast assistant into a careful one: automation you trust because it can’t slip.
Source: Anthropic docs — settings reference, hooks ↗3 · Your own dashboard: statusLine
Claude Code can render a custom status line under your prompt — and you get to decide what it shows. The value is an object naming a command, and Claude Code runs that command to draw the line: model, cost, git branch, whatever you print.
{
"statusLine": {
"type": "command",
"command": "echo \"$(git branch --show-current)\""
}
}You’re switching between feature branches all day and keep typing git branch just to confirm where you are before letting Claude run anything destructive. A status line that prints the current branch — or the model in use and your context usage — means the answer is always one glance down, no command needed. It’s the cheapest situational-awareness upgrade in the whole settings file.
The information you check five times a day belongs in your periphery, not in a command you keep retyping.
Source: Anthropic docs — settings reference, statusLine ↗4 · Set your default brain: model
This key sets the model every new session uses, so you don’t have to pick one with /model each time. And /model saves your choice right back here — it writes the value into your settings file as the default for new sessions.
{
"model": "claude-opus-5-5"
}Setting the key doesn’t stop you from switching mid-session. And per-session overrides exist: ANTHROPIC_MODEL exported in your shell applies over the model key from any file, and --model takes precedence over both for that one session.
A team pins the same model in the shared project settings so every session — yours, your teammate’s, the CI-adjacent ones — starts on identical footing, which makes debugging behavior differences much easier. An individual might instead keep their personal favorite in their user settings and switch per session with /model when a task needs something else.
One line, set once, and you never burn the first minute of a session picking a model again.
Source: Anthropic docs — settings reference, model ↗5 · Change Claude’s personality: outputStyle
An output style is a saved set of instructions that changes Claude’s role, tone, and output format — and this key picks one by name for your sessions. Anthropic ships built-in styles such as Explanatory and Learning, and you can write your own.
{
"outputStyle": "Explanatory"
}You’re onboarding onto an unfamiliar codebase: set the Explanatory style and Claude weaves the “why” into its work, teaching as it goes. When the deadline looms and you want answers, not lessons, switch to a terse custom style of your own. Changing the key mid-session takes effect from your next message, so the switch is cheap.
Same model, different posture — the style key is how you tell Claude who to be for the task at hand.
Source: Anthropic docs — settings reference, outputStyle ↗6 & 7 · Control the memory tidy-up: autoCompactEnabled & autoCompactWindow
When a session’s context fills up, Claude Code can compact it automatically — summarizing the conversation so far and continuing with a slimmer one. These two keys are the on/off switch and the tripwire.
autoCompactEnabled turns the automatic behavior off or on (it’s on by default). Set it to false and Claude stops compacting on its own — though the manual /compact command keeps working whenever you want it. autoCompactWindow sets how full the context window gets, in tokens, before the automatic compaction kicks in — anywhere from 100,000 to 1,000,000, capped at your model’s window. Leave it unset and Claude Code picks a window tuned for your model.
{
"autoCompactEnabled": false
}{
"autoCompactWindow": 250000
}You’re deep in a long debugging session where context is everything and an untimely summary could lose a thread. Turning auto-compact off puts you in charge: you decide when to call /compact. Alternatively, on a model with a huge context window, raising autoCompactWindow pushes the automatic tidy-up later — the summaries arrive only when the context is genuinely full.
Automatic is convenient; deliberate is powerful. These two keys let you pick which one a given session gets.
Source: Anthropic docs — settings reference, autoCompactEnabled & autoCompactWindow ↗Bonus: two tips worth thirty seconds
Two small things that make everything above easier to work with.
Add a $schema key at the top of your settings file pointing at the published JSON schema for Claude Code settings. VS Code, Cursor, and any editor that understands JSON schema then gives you autocomplete and inline validation for every key — no more guessing whether it’s defaultMode or default-mode.
Inside Claude Code, run /config and flip options — theme, verbose output, auto-compact — without opening an editor. Most choices save to your user settings file, and to set one option without the menu at all, pass it directly: /config verbose=true.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "claude-opus-5-5"
}FAQ
Put personal preferences in your user settings, ~/.claude/settings.json — it applies to every project on your machine. Put team rules in the shared project file, .claude/settings.json, and commit it. Put per-project overrides in .claude/settings.local.json, which stays yours only. Remember: the auto and bypassPermissions permission modes don’t take effect from project or local files — those two belong in your user settings.
The highest level wins: managed settings first, then a --settings flag you passed for this session, then project local, then shared project, then user settings. So your local file overrides the team’s shared file, and nothing you write overrides your organization’s managed settings.
Run /status inside Claude Code to see which settings files it actually loaded. Then run claude doctor to list the entries it rejected. The usual culprits: invalid JSON (a trailing comma or a // comment makes Claude Code skip the file), a value the schema rejects, or a higher-level file setting the same key.
Yes. The environment variable applies over the model key from any settings file, and --model takes precedence over both for that one session. The pairing is decided key by key — ANTHROPIC_MODEL is specifically paired with model.
Shared project settings apply only when you work inside that project folder, and some of what they set — like permission allow rules — waits until you trust the folder. Your project-local file applies over the shared one, so you always have a personal override that needs no commit.
Run /config inside Claude Code and change it from the menu, or skip the menu entirely with /config key=value — for example, /config verbose=true. For a one-session experiment, pass --settings with the key when you start Claude Code; nothing is written to your files.
Takeaways
- Four files, one stack. Managed > --settings > project local > shared project > user. Know where a key lives and you know who it affects and whether it wins.
- Strict JSON, real consequences. A stray comment or trailing comma makes Claude Code skip the whole file — /status shows what loaded, claude doctor shows what it rejected.
- Caution is one key. permissions.defaultMode sets how much new sessions ask before acting; auto for flow, plan for unfamiliar code. The bold modes only work from your own user file.
- Hooks guard, status lines inform. A hook can stop a secret from being committed before the command runs; a status line keeps the branch, model, or context usage in your periphery.
- The model key is a default, not a lock. ANTHROPIC_MODEL in your shell outranks it from any file; --model outranks both for one session.
- Compaction is tunable. Turn auto-compact off and drive /compact yourself for long sessions, or raise autoCompactWindow so summaries wait until the context is truly full.
Sources
Every technical claim in this guide — the four files, the precedence order, the seven keys, their scopes, and the $schema and /config tips — comes from Anthropic’s official Claude Code documentation, read on October 4, 2026. The apartment analogy, use cases, and code examples are our own.
- Anthropic docs — Settings files and precedence: the four files, precedence stack, /status, claude doctor, the /config menu, and the $schema key ↗
- Anthropic docs — All settings (settings reference): permissions.defaultMode, hooks, statusLine, model, outputStyle, autoCompactEnabled, and autoCompactWindow ↗
Companion reel: this guide will be linked from @theclaudecraft’s “7 hidden Claude Code settings that change everything” reel once it posts.