Claude Code — Configuration · AI coding agents

Claude Code is configured through layered settings.json files plus environment variables. Adding "$schema": "https://json.schemastore.org/claude-code-settings.json" to a settings file enables editor autocomplete.

Settings locations and precedence

Highest priority first:

Priority	Scope	Location
1 (highest)	Managed (enterprise)	macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`; Linux/WSL: `/etc/claude-code/managed-settings.json`; Windows: `C:\Program Files\ClaudeCode\managed-settings.json`
2	Command-line arguments	Session-only overrides (see Claude Code — CLI Flags)
3	Local project	`.claude/settings.local.json` (gitignored automatically)
4	Project	`.claude/settings.json` (commit this to share with the team)
5 (lowest)	User	`~/.claude/settings.json`

Managed settings cannot be overridden — that’s how enterprises enforce policy.

Other state lives in ~/.claude.json: preferences, the OAuth session, user/local-scope MCP servers, and per-project state such as allowed tools and trust. Claude Code keeps timestamped backups (5 most recent) of config files.

Key settings

A representative settings.json:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "cleanupPeriodDays": 30,
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  },
  "permissions": {
    "defaultMode": "plan",
    "allow": ["Bash(npm run *)", "Read"],
    "deny": ["Read(./.env)"],
    "additionalDirectories": ["../shared-lib"]
  },
  "enabledPlugins": {
    "my-plugin@my-marketplace": true
  },
  "statusLine": { "type": "command", "command": "my-statusline.sh" }
}

Frequently used keys (all verified in the settings reference):

Key	Purpose
`model`	Default model
`apiKeyHelper`	Helper command that supplies an API key
`cleanupPeriodDays`	Session retention (default 30; `0` deletes all sessions at startup)
`env`	Environment variables applied to every session
`permissions`	`allow` / `ask` / `deny` / `additionalDirectories` / `defaultMode` / `disableBypassPermissionsMode` — see Claude Code — Permissions
`hooks`	Event hooks; `disableAllHooks` turns them off
`attribution`	`commit`, `pr` — replaces the deprecated `includeCoAuthoredBy`
`outputStyle`	Output style (e.g. `Explanatory`)
`statusLine`	Custom status line command
`respectGitignore`	Respect `.gitignore` in file operations
`fileSuggestion`	File-suggestion behavior for `@` mentions
`enableAllProjectMcpServers`	Auto-enable `.mcp.json` servers
`enabledMcpjsonServers` / `disabledMcpjsonServers`	Per-server `.mcp.json` allow/deny lists
`forceLoginMethod`	`claudeai` or `console`
`forceLoginOrgUUID`	Pin login to an organization
`autoUpdatesChannel`	`stable` or `latest`
`plansDirectory`	Where plan-mode plans are stored (default `~/.claude/plans`)
`language`	Response language
`showTurnDuration` / `spinnerVerbs` / `spinnerTipsEnabled`	TUI cosmetics
`terminalProgressBarEnabled` / `prefersReducedMotion`	TUI behavior
`teammateMode`	Agent-team display mode
`awsAuthRefresh` / `awsCredentialExport`	Bedrock credential handling
`alwaysThinkingEnabled`	Keep extended thinking on
`companyAnnouncements`	Announcements shown to users

Managed-only keys (enterprise policy): allowManagedHooksOnly, allowManagedPermissionRulesOnly, allowedMcpServers, deniedMcpServers, strictKnownMarketplaces.

Plugin keys: enabledPlugins (format "plugin@marketplace": true/false), extraKnownMarketplaces.

Sandbox keys (sandbox.enabled, autoAllowBashIfSandboxed, network rules, …) are covered in Claude Code — Permissions.

Environment variables

All of these can also be set inside settings.json under env.

Variable	Purpose
`ANTHROPIC_API_KEY`	API key authentication
`ANTHROPIC_AUTH_TOKEN`	Custom auth token
`ANTHROPIC_CUSTOM_HEADERS`	Extra headers on API requests
`ANTHROPIC_MODEL`	Default model
`ANTHROPIC_DEFAULT_HAIKU_MODEL` / `_OPUS_MODEL` / `_SONNET_MODEL`	Per-tier model overrides
`CLAUDE_CODE_USE_BEDROCK` / `_VERTEX` / `_FOUNDRY`	Route via a third-party cloud
`AWS_BEARER_TOKEN_BEDROCK`	Bedrock bearer token
`CLAUDE_CODE_SUBAGENT_MODEL`	Model used by subagents
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Output cap (default 32,000; max 64,000)
`MAX_THINKING_TOKENS`	Thinking budget (default 31,999; `0` disables thinking)
`CLAUDE_CODE_EFFORT_LEVEL`	`low` / `medium` / `high` (Opus 4.6+)
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Auto-compact trigger percentage (default ~95)
`BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` / `BASH_MAX_OUTPUT_LENGTH`	Bash tool limits
`CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`	Keep Bash in the project directory
`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`	Also load `CLAUDE.md` from `--add-dir` directories
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	Disable automatic memory (see Claude Code — Project Instructions (CLAUDE.md))
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	Disable background tasks
`CLAUDE_CONFIG_DIR`	Relocate the config directory
`DISABLE_AUTOUPDATER`	Turn off auto-updates
`DISABLE_TELEMETRY` / `DISABLE_ERROR_REPORTING` / `DISABLE_COST_WARNINGS`	Privacy/UX toggles
`ENABLE_TOOL_SEARCH`	Tool search (`auto` default; enables at 10% of context)
`MAX_MCP_OUTPUT_TOKENS`	MCP tool output cap (default 25,000)
`MCP_TIMEOUT` / `MCP_TOOL_TIMEOUT`	MCP startup / tool-call timeouts
`MCP_OAUTH_CALLBACK_PORT`	OAuth callback port for MCP auth
`SLASH_COMMAND_TOOL_CHAR_BUDGET`	Skill metadata budget (2% of context window; fallback 16,000 chars)
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	Proxy configuration
`CLAUDE_ENV_FILE`	File sourced before each Bash command (settable via SessionStart hooks)
`CLAUDE_CODE_SHELL` / `CLAUDE_CODE_SHELL_PREFIX`	Shell selection and wrapping
`USE_BUILTIN_RIPGREP`	Use the bundled ripgrep

Deprecated: ANTHROPIC_SMALL_FAST_MODEL, and includeCoAuthoredBy (a setting, replaced by attribution).

Notes

Edit settings interactively with /config, or set a value straight from the prompt: /config model=opus.
The legacy claude config CLI subcommand no longer appears in the current CLI reference — ? Unable to verify; use /config or edit the JSON files.
CLI flags like --settings and --setting-sources can layer extra settings per session (see Claude Code — CLI Flags).

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.