Claude Code settings

Configure Claude Code with global and project-level settings, and environment variables.

Claude Code offers a variety of settings to configure its behavior. Run /config in the interactive REPL to open the Settings interface.

Configuration scopes

Scope	Location	Who it affects	Shared with team?
Managed	Server-managed settings, plist/registry, or `managed-settings.json`	All users on the machine	Yes (deployed by IT)
User	`~/.claude/` directory	You, across all projects	No
Project	`.claude/` in repository	All collaborators	Yes (committed to git)
Local	`.claude/settings.local.json`	You, in this repository only	No (gitignored)

Precedence (highest first): Managed → Command line arguments → Local → Project → User.

Permission rules merge across scopes; deny always wins over allow.

When to use each scope

Managed — security policies, compliance, IT-standardized config
User — personal preferences, API keys, tools across all projects
Project — team permissions, hooks, MCP servers, shared plugins
Local — personal overrides, experiments before sharing with the team

Settings files

User: ~/.claude/settings.json
Project: .claude/settings.json (shared), .claude/settings.local.json (personal, gitignored)
Managed: macOS /Library/Application Support/ClaudeCode/, Linux /etc/claude-code/, Windows C:\Program Files\ClaudeCode\

Other configuration lives in ~/.claude.json (OAuth, MCP for user/local scopes, per-project state). Project MCP servers use .mcp.json.

Example:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "companyAnnouncements": [
    "Welcome! Review our code guidelines at docs.example.com"
  ]
}

Add "$schema" for autocomplete in VS Code, Cursor, and other editors.

When edits take effect

Claude Code watches settings files and reloads most keys when they change (permissions, hooks, apiKeyHelper, etc.).

Read once at session start (restart or /clear for file edits):

model — use /model mid-session instead
outputStyle — part of system prompt rebuilt on /clear or restart

Editing CLAUDE.md mid-session does not apply until /clear, /compact, or restart.

What uses scopes

Feature	User	Project	Local
Settings	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
Subagents	`~/.claude/agents/`	`.claude/agents/`	—
MCP servers	`~/.claude.json`	`.mcp.json`	`~/.claude.json` (per-project)
Plugins	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
CLAUDE.md	`~/.claude/CLAUDE.md`	`CLAUDE.md` or `.claude/CLAUDE.md`	`CLAUDE.local.md`

On Windows, ~/.claude resolves to %USERPROFILE%\.claude.

Essential settings

Key	Description
`permissions`	`defaultMode`, `allow`, `ask`, `deny` — see Permissions
`model`	Default model; overridden by `--model` or `ANTHROPIC_MODEL`
`env`	Environment variables for every session and subprocesses
`hooks`	Commands at lifecycle events
`autoMemoryEnabled`	Toggle auto memory; also `/memory`
`claudeMdExcludes`	Glob patterns to skip CLAUDE.md files in monorepos
`additionalDirectories`	Extra directories Claude may access
`disableAutoMode`	`"disable"` removes auto from Shift+Tab cycle
`disableBypassPermissionsMode`	`"disable"` blocks bypass mode
`forceLoginMethod`	`claudeai` or `console` (managed)
`minimumVersion`	Floor for auto-updates and `claude update`

The official settings page documents every key in the full reference table.

Managed settings

Organizations deploy managed-settings.json, MDM policies, or server-managed settings that cannot be overridden by user or project settings.

Managed-only examples: allowManagedPermissionRulesOnly, allowManagedHooksOnly, strictKnownMarketplaces, claudeMd for org-wide instructions.

Use managed settings for technical enforcement (permissions.deny, sandbox.enabled, env). Use managed CLAUDE.md for behavioral guidance Claude follows but that is not hard-enforced like deny rules.