Settings, Permission Rules & Config

Everything Claude Code does is shaped by configuration — which model runs, whether it can push to git, what color the prompt is, which plugins load. That configuration does not live in one place. It lives in a stack of settings.json files plus a few command-line overrides, and they merge along a fixed precedence chain.

The key idea: this is not "one file wins." Each layer contributes keys, and when two layers set the same key, the higher-precedence layer wins for that key. Layers you didn't touch fall through to whatever the lower layers set. So your project's settings.json can pin a model while your user-level ~/.claude/settings.json still supplies your theme — they compose.

There are three reasons the layering exists, and they map onto who should control what:

• Per-user preferences (~/.claude/settings.json) — your theme, your editor mode, defaults you want everywhere.
• Per-project settings (.claude/settings.json, checked into the repo) — conventions the whole team shares: allowed commands, hooks, model.
• Per-machine / personal-to-this-repo (.claude/settings.local.json, gitignored) — overrides just for you on this checkout, not shared with teammates.
• Org policy (managed settings) — rules an administrator imposes that no lower layer can override.

Get the precedence chain in your head first; the rest of the lesson is detail hung on that spine.

Here is the full chain, highest precedence at the top. When the same key is set in two places, the higher entry wins:

There is a deliberate twist at the bottom. Normally "higher wins," but managed policy is special: although it sits at the bottom of the merge, an administrator's managed settings are designed so the layers above cannot relax them. A managed deny rule stays denied even if your project tries to allow it. Think of managed policy as a hard floor the rest of the stack builds on, not a value you can shout over.

Walking the chain with an example — suppose all of these set a model:

CLI:                 claude --model opus        ← wins this run
--settings file:     { "model": "sonnet" }
settings.local.json: { "model": "sonnet" }
settings.json:       { "model": "haiku" }
~/.claude:           { "model": "sonnet" }

The session runs on opus — the CLI flag beats everything. Remove the flag and --settings wins; remove that and settings.local.json wins; and so on down. Each key resolves independently down this same ladder.

The most consequential block in settings.json is permissions. It holds three lists — allow, ask, and deny — that govern what Claude may run, with pattern syntax targeting specific tools and commands.

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(git log *)", "Bash(npm test)", "Read"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(rm -rf *)", "Read(./.env)", "Read(./secrets/**)"]
  }
}

What each list means:

• allow — run without prompting. Use it for the safe, repetitive stuff (git status, git diff, npm test).
• ask — always prompt, even if a mode would otherwise auto-approve. Use it to force a human checkpoint on sensitive-but-allowed actions.
• deny — never run, no prompt. deny wins over everything — it overrides the active permission mode and any allow rule.

Pattern syntax. A rule is Tool(pattern):

Manage all of this without hand-editing JSON using /permissions (alias /allowed-tools): it lists active rules and recent denials, and lets you turn a denial into a rule on the spot (press r to retry). And to generate a sensible allow-list automatically, run /fewer-permission-prompts — it scans your session transcripts for the safe, read-only commands you keep approving and proposes an allowlist to add to your project .claude/settings.json, cutting future prompts.

You can also allow-list for a single run from the CLI with the same rule syntax:

claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

Beyond permissions, a handful of settings.json keys carry real weight. Here are the ones worth knowing by name:

The env block is how you set environment variables declaratively in settings rather than exporting them in your shell:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Two env vars you'll reach for often:

• DISABLE_AUTOUPDATER=1 — turns off only the background auto-update (use DISABLE_UPDATES=1 to stop all update paths). Handy on locked-down or offline machines, and it pairs naturally with minimumVersion for controlled rollouts.
• CLAUDE_CODE_GIT_BASH_PATH — on Windows, points Claude Code at your Git Bash executable so the Bash tool works (otherwise it falls back to the PowerShell tool).

hooks deserve a special mention. Unlike CLAUDE.md instructions — which are advisory (Claude may or may not follow them) — a hook is a shell command Claude Code runs at a lifecycle point (PreToolUse, PostToolUse, Stop, SessionStart, and more). Hooks are deterministic and guaranteed. When you need an action to always happen, configure a hook in settings; don't merely ask in conversation.

Not every setting is something you want to edit by hand. The interactive layer covers the everyday cosmetic and ergonomic choices.

/config (alias /settings) opens the settings UI. From there you set:

• Theme — light / dark / auto and accessibility variants.
• Editor mode — toggle vim keybindings vs the default editor mode. (The old /vim command was removed; this lives in /config → Editor mode now.)
• Output style — how Claude formats its responses.
• Prompt suggestions — turn the suggestion hints on or off.
• The release channel (latest vs stable) and model can also be chosen here.

/theme jumps straight to theme selection — auto, light, dark, colorblind-friendly (daltonized) variants, ANSI, or a custom theme from ~/.claude/themes/.

/color [color] sets the accent color of your prompt — a quick way to visually distinguish multiple concurrent sessions or environments (e.g., a red prompt for a production-adjacent checkout).

These interactive choices are written back into your settings files, so they persist across sessions and still obey the same precedence chain — a theme set in /config lands in ~/.claude/settings.json unless a higher layer overrides it.

Plugins are bundles of capability you install into Claude Code. A single plugin can package any mix of skills, tools, MCP servers, and hooks, and plugins are distributed through marketplaces — curated collections you install from.

Manage them from the CLI:

claude plugin install code-review@claude-plugins-official   # install from a marketplace
claude plugin list                                          # list installed plugins
claude plugin remove code-review                            # uninstall

Inside a session, /plugins opens the plugin manager (browse, install, enable/disable) and /reload-plugins hot-reloads them after a change.

For local development or a one-off, load a plugin straight from a directory or .zip for the current session — no install required:

claude --plugin-dir ./my-plugin     # repeatable; loads for this session only

This is the right tool for testing a plugin you're building, or pulling in a capability for a single run without committing to a global install. Because a plugin can carry MCP servers and hooks, installing one is a meaningful trust decision — it can wire commands into your lifecycle and connect external services. Install from marketplaces you trust, and review what a plugin bundles before enabling it.

The bottom of the precedence chain is reserved for administrators. Managed policy (also called enterprise managed settings) lets an organization impose configuration that the layers above cannot override — the one place where "lower in the chain" still means "final word."

Managed policy is delivered as a settings file (and a managed-policy CLAUDE.md) installed at OS-level system paths an ordinary user can't edit. Its purpose is governance: an admin can guarantee that across every developer's machine, certain commands are denied, a minimumVersion floor is enforced, auto-updates follow a chosen channel, or a particular CLAUDE.md is always loaded.

The critical properties:

• A managed deny rule cannot be relaxed by a project allow rule or a user setting. Org-level prohibitions hold everywhere.
• A managed-policy CLAUDE.md cannot be excluded by claudeMdExcludes — org instructions always load.
• It composes with everything else: managed policy sets the floor, and the personal/project/CLI layers build on top of it for everything the policy leaves open.

This is how enterprises combine the flexibility developers need with the guarantees compliance requires: individuals still pick their theme, model, and project rules, while the organization keeps a non-negotiable safety and consistency baseline underneath.