Claude Code settings.json Deep Dive (4): env, Models, Auth, and Other Useful Fields

Introduction

The first three posts covered the configuration file hierarchy (part 1), the permissions system (part 2), and hooks (part 3). This final installment goes through all the remaining useful fields — they may not get as much spotlight as the previous topics, but they cover the knobs you are most likely to reach for day to day.

Content is grouped by function for easy reference.

---

env — Inject Environment Variables

{
  "env": {
    "NODE_ENV": "development",
    "MY_API_URL": "https://api.example.com",
    "DEBUG": "true"
  }
}

env is a Record<string, string>. Claude Code injects these key-value pairs into the session’s environment at startup. Every command executed via the Bash tool and every hook script can read these variables.

Common uses:

• Set fixed environment variables for all Bash commands without manually running export each time
• Commit project-specific variables to project settings so the whole team shares the same environment
• Temporarily inject sensitive config via --settings in CI pipelines (combined with managed settings)

Note: Values must be plain strings — dynamic evaluation is not supported. For dynamic secrets, use apiKeyHelper described below.

---

Model Configuration

model — Override the Default Model

{
  "model": "claude-sonnet-4-6"
}

Overrides the model Claude Code uses. Set it globally in user settings or per-project in project settings. Valid values: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001.

availableModels — Model Allowlist

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

Restricts which models users can switch to via the /model command. Models not on the list will not appear in the selection UI. Useful for teams that want to prevent accidental use of expensive models.

modelOverrides — Model ID Mapping

{
  "modelOverrides": {
    "claude-sonnet-4-6": "anthropic/claude-sonnet-4-6-custom"
  }
}

Maps standard Anthropic model IDs to provider-specific model IDs. Useful when routing Claude calls through a third-party API proxy.

---

Authentication Helpers

apiKeyHelper — Dynamic API Key Retrieval

{
  "apiKeyHelper": "/path/to/get-api-key.sh"
}

Path to an executable script that Claude Code runs whenever it needs an API key. The script’s stdout is used as the credential value. Ideal when:

• Keys are stored in a secrets manager (1Password, HashiCorp Vault, etc.) and must be fetched at runtime
• Keys rotate frequently and cannot be hardcoded as environment variables

The script just needs to print the key string to stdout — no special format required.

awsCredentialExport / awsAuthRefresh

{
  "awsCredentialExport": "/path/to/export-aws-creds.sh",
  "awsAuthRefresh": "/path/to/refresh-aws.sh"
}

For AWS Bedrock integration:

• awsCredentialExport: path to a script that exports AWS credentials (export AWS_ACCESS_KEY_ID=... format)
• awsAuthRefresh: path to a script that refreshes expired credentials

gcpAuthRefresh

{
  "gcpAuthRefresh": "gcloud auth application-default login"
}

Google Cloud authentication refresh command. When using Vertex AI as the backend, Claude Code automatically runs this command when credentials expire.

---

Git and Commit Attribution

attribution — Customize Commit Attribution

{
  "attribution": {
    "coAuthoredBy": true,
    "coAuthorName": "My Claude",
    "coAuthorEmail": "claude@example.com"
  }
}

Customizes the Co-authored-by attribution Claude Code adds to commits and PRs.

Field	Type	Description
coAuthoredBy	boolean	Whether to include a Co-authored-by line in commits
coAuthorName	string	Display name for the co-author
coAuthorEmail	string	Email address for the co-author

includeCoAuthoredBy (Deprecated)

{
  "includeCoAuthoredBy": false
}

Controls whether Claude’s Co-authored-by attribution is added to commits. Defaults to true. This field is deprecated in favor of attribution — migrate when possible. Set to false to remove AI attribution entirely.

includeGitInstructions

{
  "includeGitInstructions": false
}

Controls whether built-in Git commit and PR workflow instructions are included in the system prompt. Defaults to true. If your CLAUDE.md already defines a complete Git workflow, set this to false to avoid duplication.

---

Session and Cleanup

cleanupPeriodDays — Transcript Retention

{
  "cleanupPeriodDays": 60
}

Number of days to retain chat transcripts. Defaults to 30 days. Transcripts older than this value are automatically deleted.

Special value: set to 0 to disable session persistence entirely — Claude Code will not write any chat history to disk. Useful for environments with strict privacy requirements.

---

Language and UI

language — Response Language

{
  "language": "japanese"
}

Sets Claude’s preferred response language. Accepts natural language names like "chinese", "japanese", "spanish", etc. This field also affects the language used for voice dictation recognition.

When unset, Claude defaults to responding in the language the user writes in.

syntaxHighlightingDisabled

{
  "syntaxHighlightingDisabled": true
}

Disables syntax highlighting in the diff view. Useful when the terminal has rendering issues with highlighted output.

terminalTitleFromRename

{
  "terminalTitleFromRename": false
}

Controls whether the /rename command also updates the terminal tab title. Defaults to true. Set to false if you do not want this behavior.

spinnerTipsEnabled

{
  "spinnerTipsEnabled": false
}

Controls whether tips are shown in the spinner while Claude is thinking. Enabled by default. Turn it off for a cleaner interface.

prefersReducedMotion

{
  "prefersReducedMotion": true
}

Reduces or disables UI animations. Useful for users sensitive to motion or for accessibility needs.

---

Thinking Depth and Efficiency

effortLevel — Thinking Depth

{
  "effortLevel": "high"
}

Persists the thinking depth setting across sessions, equivalent to running /effort every time. Three values:

Value	Effect
low	Faster replies with less deliberation
medium	Default balance
high	Deep thinking, suited for complex tasks

Only effective on models that support Extended Thinking (Opus, Sonnet).

alwaysThinkingEnabled

{
  "alwaysThinkingEnabled": false
}

Set to false to completely disable the thinking feature. When absent or true, thinking is enabled automatically by the model as needed.

fastMode

{
  "fastMode": true
}

Enables Fast Mode persistently, equivalent to running /fast. Combined with fastModePerSessionOptIn:

{
  "fastModePerSessionOptIn": true
}

When fastModePerSessionOptIn is true, the Fast Mode setting does not persist across sessions — it resets every time Claude Code starts.

---

Auto-Updates

autoUpdatesChannel — Update Channel

{
  "autoUpdatesChannel": "stable"
}

Controls which release channel Claude Code auto-updates from:

Value	Description
latest	Newest version (may include pre-release features)
stable	Stable releases (more thoroughly tested)

minimumVersion — Downgrade Protection

{
  "minimumVersion": "2.1.88"
}

Prevents Claude Code from downgrading below the specified version. When switching to the stable channel, this field blocks the downgrade if the stable version is lower than the current one.

---

Memory System

autoMemoryEnabled — Automatic Memory

{
  "autoMemoryEnabled": true
}

Enables the auto-memory feature for the current project. Claude Code automatically persists important information learned during conversations for use in future sessions.

autoMemoryDirectory — Memory Storage Path

{
  "autoMemoryDirectory": ".claude/memory"
}

Customizes the directory where memory files are stored (relative to the project root). Defaults to Claude Code’s built-in memory directory.

autoDreamEnabled — Background Memory Consolidation

{
  "autoDreamEnabled": true
}

Enables Auto Dream — background consolidation and deduplication of existing memories, keeping the memory store clean and organized.

---

MCP Server Management

enableAllProjectMcpServers

{
  "enableAllProjectMcpServers": true
}

Automatically approves all MCP servers listed in .mcp.json without requiring individual confirmation. Suitable when you fully trust the project’s MCP configuration.

enabledMcpjsonServers / disabledMcpjsonServers

{
  "enabledMcpjsonServers": ["github", "playwright"],
  "disabledMcpjsonServers": ["legacy-tool"]
}

Fine-grained control over which MCP servers from .mcp.json are enabled or disabled. Both fields are arrays of server names and follow the array merge rule described in part 1 — values from multiple config layers are concatenated.

---

Other Useful Fields

defaultShell

{
  "defaultShell": "bash"
}

Default shell for ! commands in the input box. Options: "bash" or "powershell". Defaults to "bash".

respectGitignore

{
  "respectGitignore": false
}

Controls whether the file picker (@ mentions) respects .gitignore rules. Defaults to true. Note: .ignore files are always respected regardless of this setting.

plansDirectory — Plan File Location

{
  "plansDirectory": ".claude/plans"
}

Customizes the directory where /plan command output is stored (relative to the project root).

disableAllHooks

{
  "disableAllHooks": true
}

Disables all hooks and statusLine execution in one switch. Very useful for debugging configuration issues — eliminate hooks as a variable first, then re-enable them incrementally.

feedbackSurveyRate

{
  "feedbackSurveyRate": 0
}

Probability (0–1) that the session quality survey appears when eligible. Set to 0 to completely disable the feedback popup.

---

Enterprise-Only Fields

The following fields only take effect when set in managed-settings.json. Writing them in user or project settings has no effect:

Field	Description
allowManagedHooksOnly	Only hooks defined in managed settings are executed
allowManagedPermissionRulesOnly	Only permission rules from managed settings are respected
allowManagedMcpServersOnly	MCP server allowlist is only read from managed settings
allowedMcpServers	Enterprise allowlist of permitted MCP servers
deniedMcpServers	Enterprise blocklist of forbidden MCP servers
strictPluginOnlyCustomization	Restrict customization to plugins only (blocks local skills/agents/hooks)
forceLoginMethod	Force a specific login method (claudeai or console)
forceLoginOrgUUID	Force binding to a specific organization UUID

---

Quick Reference: All settings.json Fields

A summary table spanning all four posts for easy daily reference:

Category	Fields	Summary
Base	$schema	JSON Schema ref (editor autocomplete)
Hierarchy	See part 1	File paths, priority, merge rules
Permissions	permissions	allow/deny/ask rules — see part 2
Hooks	hooks, disableAllHooks	Lifecycle hooks — see part 3
Env Vars	env	Inject env vars into the session
Models	model, availableModels, modelOverrides	Model selection and restrictions
Auth	apiKeyHelper, awsCredentialExport, gcpAuthRefresh	Dynamic credential retrieval
Git	attribution, includeCoAuthoredBy, includeGitInstructions	Commit attribution and Git prompts
Session	cleanupPeriodDays	Transcript retention period
UI	language, syntaxHighlightingDisabled, prefersReducedMotion	Language and interface
Thinking	effortLevel, alwaysThinkingEnabled, fastMode	Thinking depth and speed
Updates	autoUpdatesChannel, minimumVersion	Update channel control
Memory	autoMemoryEnabled, autoMemoryDirectory, autoDreamEnabled	Auto-memory system
MCP	enableAllProjectMcpServers, enabledMcpjsonServers	MCP server management

---

Wrapping Up

This four-part series has covered the full settings.json surface:

• Part 1: Five-layer config hierarchy — file locations and priority rules
• Part 2: permissions — allow/deny/ask rules, wildcards, defaultMode
• Part 3: hooks — four hook types, four core events, stdin/stdout protocol
• Part 4: env, models, auth, Git, sessions, UI, thinking, updates, memory, and more

Nearly every common “how do I make Claude Code do X” question maps to one of these fields. When you hit that question, this is the first place to look.