Configuration

Claude Code is configured at multiple levels — global user settings, project-local settings, CLAUDE.md instruction files, CLI flags, and MDM-managed enterprise policies. Settings are merged at runtime with a defined precedence order.

Config file locations

Global user config (~/.claude/settings.json)

The global settings file applies to every Claude Code session on your machine. Create or edit it at:

~/.claude/settings.json

Example:

{
  "$schema": "https://claude.ai/schema/settings.json",
  "model": "claude-opus-4-5",
  "permissions": {
    "defaultMode": "default"
  },
  "env": {
    "MY_VAR": "value"
  }
}

Add "$schema" to get autocomplete and validation in editors that support JSON Schema.

Project-local config (.claude/settings.local.json)

The project-local config file lives inside your project directory and is merged on top of the global config for sessions in that project. It is not committed to version control (add .claude/settings.local.json to .gitignore).

<project-root>/.claude/settings.local.json

Project shared config (.claude/settings.json)

A project-shared settings file can be committed alongside your code. It applies to every team member who opens Claude Code in that project.

<project-root>/.claude/settings.json

CLAUDE.md instruction files

CLAUDE.md files contain natural-language instructions that are injected into Claude’s system prompt. Claude Code reads them from:

~/.claude/CLAUDE.md — global instructions for all projects
<project-root>/CLAUDE.md — project-level instructions (can be committed)
Any subdirectory CLAUDE.md — applied when Claude operates in that subdirectory

Use CLAUDE.md for instructions, conventions, and context that would otherwise need to be repeated in every conversation — for example, coding standards, project architecture notes, or preferred test frameworks.

# My Project

## Coding conventions
- Use TypeScript strict mode
- Prefer `const` over `let`
- All public functions must have JSDoc comments

## Testing
- Use Vitest for unit tests
- Run `npm test` before committing

Enterprise managed settings

Enterprise administrators can push settings to all users via MDM (Mobile Device Management) or a managed settings file. These are applied with the highest precedence and cannot be overridden by user or project settings. See MDM-managed settings below.

Key settings

Model selection

Override the default model Claude Code uses. Accepts a full model ID or a version alias.

{
  "model": "claude-opus-4-5"
}

Enterprise administrators can restrict which models are available using availableModels:

{
  "availableModels": ["claude-opus-4-5", "claude-sonnet-4-5"]
}

If availableModels is set to an empty array, only the default model is selectable.

Permission mode

Controls how Claude Code handles tool permission requests. Set via permissions.defaultMode:

Mode	Description
`default`	Prompts for approval on potentially destructive actions
`acceptEdits`	Auto-approves file reads and edits in the working directory; prompts for shell commands
`plan`	Shows a plan before executing any tools
`bypassPermissions`	Skip all permission prompts (use with caution in isolated environments)
`dontAsk`	Skip all prompts silently (non-interactive automation)

{
  "permissions": {
    "defaultMode": "default"
  }
}

You can also define fine-grained allow, deny, and ask rules:

{
  "permissions": {
    "allow": ["Bash(git *)", "Read(**/*.ts)"],
    "deny": ["Bash(rm -rf *)"]
  }
}

Output format and themes

Change the terminal theme with the /theme slash command, or set it in config:

{
  "theme": "dark"
}

Adjust session transcript retention (days). Set 0 to disable persistence:

{
  "cleanupPeriodDays": 30
}

Environment variables

Inject environment variables into every Claude Code session:

{
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "https://api.example.com"
  }
}

Hooks

Run custom shell commands before or after tool executions. See Hooks for full documentation.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo 'Running bash'" }]
      }
    ]
  }
}

Git and commit attribution

Control whether Claude Code adds co-authored-by attribution to commits and PRs:

{
  "attribution": {
    "commit": "Co-authored-by: Claude <noreply@anthropic.com>",
    "pr": ""
  }
}

Setting pr to an empty string removes attribution from PR descriptions. Set includeGitInstructions: false to remove built-in git workflow instructions from Claude’s system prompt.

The `/config` slash command

Run /config inside a Claude Code session to open the interactive settings UI. From there you can:

View your current effective settings (merged from all sources)
Change individual settings and see them take effect immediately
Switch between the Config and Permissions tabs

The settings UI shows the resolved value for each setting and which source it came from (user, project, managed).

Environment variables

Several environment variables influence Claude Code’s runtime behavior without modifying config files:

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key for direct API authentication
`ANTHROPIC_BASE_URL`	Override the Anthropic API base URL
`CLAUDE_CODE_DISABLE_POLICY_SKILLS`	Set to `1` to skip loading managed skills
`CLAUDE_CODE_COORDINATOR_MODE`	Set to `1` to enable multi-agent coordinator mode
`CLAUDE_CODE_SIMPLE`	Set to `1` for a reduced tool set in coordinator workers
`CLAUDE_CODE_ENABLE_XAA`	Set to `1` to enable Cross-App Access for MCP OAuth

Environment variables take effect per-process. To make them permanent, add them to your shell profile or to the env key in settings.json.

MDM-managed settings

Enterprise administrators can distribute settings to managed machines using:

macOS MDM — Deploy a configuration profile targeting Claude Code’s bundle ID
Managed settings file — Place managed-settings.json in the managed settings path

The managed settings path is platform-dependent. Retrieve it programmatically via the getManagedFilePath() utility, or contact your IT administrator. Managed settings support all keys from the standard settings schema, plus enterprise-only policy keys:

Key	Description
`allowedMcpServers`	Allowlist of MCP servers users can add
`deniedMcpServers`	Denylist of blocked MCP servers
`allowManagedMcpServersOnly`	Restrict MCP allowlist to managed settings only
`allowManagedHooksOnly`	Only run hooks defined in managed settings
`allowManagedPermissionRulesOnly`	Only respect permission rules from managed settings
`strictPluginOnlyCustomization`	Lock skills, agents, hooks, or MCP to plugin-only
`availableModels`	Allowlist of selectable models

Config precedence

When the same setting is specified in multiple places, the following precedence order applies (highest to lowest):

MDM managed settings
  ↓
Global user config (~/.claude/settings.json)
  ↓
Project shared config (<project>/.claude/settings.json)
  ↓
Project local config (<project>/.claude/settings.local.json)
  ↓
CLI flags (--permission-mode, --model, etc.)

MDM-managed settings cannot be overridden by users or projects. They are enforced by the enterprise administrator.

Permission model

Understand how Claude Code gates tool usage and requests consent.

Hooks

Run shell commands before and after tool executions.

MCP servers

Connect external tools and data sources via MCP.

Commands reference

Full reference for the /config command.

Get Started

Core Concepts

Guides

Advanced

Config file locations

Key settings

The `/config` slash command

Environment variables

MDM-managed settings

Config precedence

Permission model

Hooks

MCP servers

Commands reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Config file locations

​Key settings

​The /config slash command

​Environment variables

​MDM-managed settings

​Config precedence

​Related pages

Permission model

Hooks

MCP servers

Commands reference

Build docs developers (and LLMs) love

Config file locations

Key settings

The `/config` slash command

Environment variables

MDM-managed settings

Config precedence

Related pages