Skip to main content
Claude Code uses Zod schemas (defined in src/schemas/) to validate all configuration. The schemas import from zod/v4 (the v4-compatible API included in zod@^3.24.0). Settings are layered across three scopes, with more specific scopes overriding broader ones.

​
Configuration levels

1

User settings

Stored in ~/.claude/. Applies to all projects for the current user. Includes preferences like theme, model selection, keybindings, effort level, and privacy settings.Managed via the /config command or by editing the settings file directly.
2

Project-level settings

Stored in a CLAUDE.md file at the project root and a project config file. Applies only within the current project directory.CLAUDE.md acts as the project’s memory — it can contain conventions, architecture notes, and any context Claude should always have available. Initialize it with /init.
Use CLAUDE.md to capture project-specific facts like coding conventions, preferred libraries, and architectural decisions. Claude reads this file automatically at session start.
3

Organization / enterprise policies

Managed via MDM (Mobile Device Management). These are read-only settings pushed by an IT administrator and cannot be overridden by user or project config.Loaded at startup from remote managed settings (src/services/remoteManagedSettings/). Enforced via policy limits (src/services/policyLimits/).

​
Viewing and modifying config

Use the /config command to interactively view and modify settings: 
/config
To modify configuration programmatically from within a session, use the updateConfig skill: 
/skills updateConfig
The ConfigTool is also available to the agent for reading or writing configuration during tool-call loops.

​
Permission rules

Permission rules control which tool invocations are automatically approved without prompting the user. Rules are stored in your settings and evaluated against each tool call before execution. Rules use a wildcard pattern syntax: 
Bash(git *)           # Allow all git commands
Bash(npm test)        # Allow 'npm test' specifically
FileEdit(/src/*)      # Allow edits to anything under src/
FileRead(*)           # Allow reading any file
Manage permission rules with the /permissions command.
Overly broad rules like Bash(*) or FileEdit(*) effectively disable the permission system for those tools. Scope rules as narrowly as practical.

​
Config schemas

All configuration shapes are defined as Zod schemas in src/schemas/. This includes:
SchemaPurpose
User settingsPersonal preferences, model, theme, keybindings
Project-level settingsPer-project context and overrides
Organization policiesMDM-enforced enterprise settings
Permission rulesTool invocation allow-lists
Hook schemasPre/post tool execution hook definitions
Hook schemas (src/schemas/hooks.ts) define four hook types:
Runs a shell command before or after a tool invocation.
{
  type: 'command',
  command: 'npm run lint',
  if: 'FileEdit(*.ts)',       // Only runs for TypeScript file edits
  shell: 'bash',
  timeout: 30,
  statusMessage: 'Linting...',
  once: false,
  async: false,
}
Evaluates an LLM prompt as a hook, passing tool input via $ARGUMENTS.
{
  type: 'prompt',
  prompt: 'Review this change for security issues: $ARGUMENTS',
  if: 'FileEdit(*)',
  model: 'claude-sonnet-4-6',
  timeout: 60,
}
Spawns a sub-agent to verify a condition. The agent exits with code 2 to block execution.
{
  type: 'agent',
  prompt: 'Verify that unit tests ran and passed.',
  if: 'Bash(npm test)',
  timeout: 60,
  model: 'claude-sonnet-4-6',
}
POSTs the hook input JSON to an HTTP endpoint.
{
  type: 'http',
  url: 'https://hooks.example.com/claude',
  if: 'Bash(git commit*)',
  headers: {
    'Authorization': 'Bearer $MY_TOKEN',
  },
  allowedEnvVars: ['MY_TOKEN'],
  timeout: 10,
}

​
Config migrations

The src/migrations/ directory handles config format changes between Claude Code versions. When you upgrade, migrations automatically read your old config and transform it to the current schema — no manual intervention required.
CLAUDE.md is part of the memory system. For more detail on how project memory, user memory, and auto-extracted memories work together, see the Memory subsystem documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us