Configuration & Settings

Claude Code's behavior is controlled by JSON settings files — you can tell it which commands to allow or deny, which model to use, and how to handle git attribution, all without touching any code.

Settings files and precedence

Claude Code reads settings from several files layered on top of each other. When the same key appears in multiple files, the higher-priority file wins. Think of it as a stack of sticky notes — lower ones only show through where higher ones don't cover them.

1 (lowest) — User: ~/.claude/settings.json — your personal defaults across all projects
2 — Project: .claude/settings.json — committed to the repo, shared with your whole team
3 — Local: .claude/settings.local.json — your personal overrides for this repo only (gitignored)
4 — Command-line arguments — one-off flags for the current session only
5 (highest) — Managed: enterprise IT-deployed policies — cannot be overridden by anything

Which file should you edit?

For personal preferences (your editor mode, preferred language), use ~/.claude/settings.json. For team-wide rules (what commands Claude is allowed to run in this repo), use .claude/settings.json and commit it. For personal tweaks that shouldn't go in git, use .claude/settings.local.json.

Permissions

The permissions system lets you pre-approve or block specific actions so Claude doesn't have to stop and ask every time. You write rules as 'ToolName(pattern)' strings inside allow, deny, or ask arrays. Rules from all scopes are merged together — a deny in your user settings still applies even if the project settings have an allow.

allow — Claude may run this without asking you first
deny — Claude is blocked from running this entirely
ask — Claude must pause and ask you before proceeding
Patterns use prefixes and wildcards, e.g. Bash(npm run test:*) to allow a family of commands
Examples: Bash(npm run test:*) allows any npm test script; Read(./.env) blocks reading your env file

Permissions merge, they don't override

Unlike most settings (where a higher-priority file wins), permission rules from all files stack together. If your user settings deny Bash(curl:*) and the project settings allow it, the deny still applies. Be intentional about what you put where.

Useful settings

Beyond permissions, a handful of settings are worth knowing early on. Most take effect immediately — Claude Code hot-reloads settings files while running. The main exception is model, read at startup; use /model to switch mid-session.

model — set a default model, e.g. 'claude-sonnet-4-6'
env — environment variables injected into every session and subprocess Claude spawns
hooks — shell commands to run at lifecycle events (before/after tool use, on session end)
disableAllHooks — boolean; set true to turn off all hooks at once
includeCoAuthoredBy — set false to drop the 'Co-authored-by Claude' line from commits and PRs
cleanupPeriodDays — how many days to keep session transcripts (default 30)
$schema — add the SchemaStore URL to get IDE autocomplete on your settings file

Example settings.json

Here is a realistic project-level .claude/settings.json that pre-approves safe commands, blocks reading secrets, sets a model, and injects an environment variable.

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development"
  },
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 14
}

Key takeaways

Settings live in layered JSON files — user, project, local, and managed. Permissions use allow/deny/ask with tool-name patterns and merge across all files rather than override. Most settings hot-reload without a restart; model is read at startup. Full reference: code.claude.com/docs/en/settings.