claude-almanac
Core

Settings and Configuration

Multi-level configuration system for Claude Code settings, permissions, and customization.

Claude Code Settings and Configuration

Claude Code uses a multi-level configuration system for settings, permissions, and customization.

Settings File Hierarchy

ScopeLocationPrecedenceAffects
ManagedSystem-level (IT-deployed)1 (Highest)All users
Local.claude/settings.local.json2Current project only
Project.claude/settings.json3Team members
User~/.claude/settings.json4 (Lowest)All projects

System-Level Managed Locations

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux/WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\Program Files\ClaudeCode\managed-settings.json

Core Settings

{
  "autoUpdatesChannel": "stable",
  "autoUpdates": true,
  "theme": "light",
  "model": "sonnet",
  "outputStyle": "Explanatory",
  "language": "english",
  "forceLoginMethod": "claudeai",
  "spinnerTipsEnabled": true,
  "showTurnDuration": true
}

Advanced Settings

SettingTypePurpose
apiKeyHelperstringScript path for dynamic API key generation
otelHeadersHelperstringScript for OpenTelemetry headers
cleanupPeriodDaysnumberDelete inactive sessions (0=immediate)
attribution.commitstringCommit message attribution (empty string hides it)
attribution.prstringPR description attribution (empty string hides it)
statusLineobjectCustom status line configuration
respectGitignorebooleanExclude .gitignore files
plansDirectorystringCustom plan file storage location
skipWebFetchPreflightbooleanSkip WebFetch domain safety check (for enterprise environments)

Environment Variables

Authentication

VariablePurpose
ANTHROPIC_API_KEYClaude API authentication
ANTHROPIC_AUTH_TOKENCustom Authorization header
ANTHROPIC_CUSTOM_HEADERSAdditional HTTP headers
ANTHROPIC_FOUNDRY_API_KEYMicrosoft Foundry API key
AWS_BEARER_TOKEN_BEDROCKAWS Bedrock API key

Model Selection

VariablePurpose
ANTHROPIC_MODELOverride default model
ANTHROPIC_DEFAULT_OPUS_MODELOpus-class model
ANTHROPIC_DEFAULT_SONNET_MODELSonnet-class model
ANTHROPIC_DEFAULT_HAIKU_MODELHaiku-class model
CLAUDE_CODE_SUBAGENT_MODELSubagent model
MAX_THINKING_TOKENSExtended thinking budget (8000-32000)

Output and Context

VariablePurposeDefault
CLAUDE_CODE_MAX_OUTPUT_TOKENSMax output tokens32000
BASH_MAX_OUTPUT_LENGTHBash output character limitSystem-dependent
BASH_DEFAULT_TIMEOUT_MSDefault bash timeout120000
BASH_MAX_TIMEOUT_MSMaximum bash timeout600000
CLAUDE_AUTOCOMPACT_PCT_OVERRIDEAuto-compaction trigger95%

MCP Configuration

VariablePurpose
MCP_TIMEOUTMCP server startup timeout
MCP_TOOL_TIMEOUTMCP tool execution timeout
MAX_MCP_OUTPUT_TOKENSMax MCP output tokens
ENABLE_TOOL_SEARCHMCP tool search mode

Feature Flags

VariablePurpose
CLAUDE_CODE_ENABLE_TELEMETRYEnable OpenTelemetry
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSDisable background operations
DISABLE_AUTOUPDATERDisable auto-updates
DISABLE_TELEMETRYOpt out of telemetry
DISABLE_ERROR_REPORTINGOpt out of Sentry errors
CLAUDE_CODE_SKIP_WEBFETCH_PREFLIGHTSkip WebFetch domain safety check

WebFetch Preflight Check

By default, Claude Code performs a domain safety verification before every WebFetch request by calling https://api.anthropic.com/api/web/domain_info?domain=<hostname>. This preflight check determines whether the domain is allowed, blocked, or if the check itself fails.

In corporate/enterprise environments, this check often fails because:

  • Corporate firewalls or proxies (e.g., ZScaler) block access to api.anthropic.com
  • Users on AWS Bedrock or Google Vertex AI may not have connectivity to api.anthropic.com
  • The check leaks domain names to Anthropic's API, which may violate privacy policies

When the preflight check fails, WebFetch refuses to fetch any URL with the error: "Unable to verify if domain <domain> is safe to fetch."

Disabling the Preflight Check

Set skipWebFetchPreflight to true in settings or via environment variable:

Settings JSON (any level):

{
  "skipWebFetchPreflight": true
}

Environment variable:

export CLAUDE_CODE_SKIP_WEBFETCH_PREFLIGHT=true

Security Considerations

RiskBenefit
Bypasses Anthropic's domain blocklistFixes WebFetch in restrictive corporate networks
Removes a prompt injection defense layerEliminates domain name leakage to api.anthropic.com
All-or-nothing (no per-domain granularity)Required for Bedrock/Vertex environments
Reduces latency (removes extra network round-trip)

Note: The WebFetch(domain:...) permission pattern provides a separate layer of domain filtering that remains active regardless of this setting.

References

Permission System

Permission Modes

ModeDescription
defaultPrompts for permission on first use
acceptEditsAuto-accepts file edit permissions
planPlan Mode - analyze only, no modifications
dontAskAuto-denies unless pre-approved
bypassPermissionsSkips all prompts

Permission Structure

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git * main)",
      "Read(~/.zshrc)",
      "Edit(./src/**)",
      "WebFetch(domain:github.com)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Bash(rm -rf:*)",
      "Read(./.env)",
      "Task(Explore)"
    ],
    "additionalDirectories": ["../docs/", "/shared/resources"]
  }
}

Rule Patterns

Bash Tool:

{
  "allow": [
    "Bash",                     // All bash commands
    "Bash(npm run build)",      // Exact match
    "Bash(npm run:*)",          // Prefix match (word boundary)
    "Bash(npm *)",              // Anywhere match (no boundary)
    "Bash(git * main)"          // Complex pattern
  ]
}

Key difference:

  • Bash(ls:*) matches ls -la but NOT lsof (word boundary)
  • Bash(ls*) matches both ls -la and lsof (no boundary)

Read/Edit/Write Tool (gitignore patterns):

{
  "allow": [
    "Read",                     // All files
    "Read(./.env)",             // Current dir file
    "Read(~/Documents/*.pdf)",  // Home directory pattern
    "Read(//Users/alice/**)",   // Absolute path
    "Edit(/src/**/*.ts)"        // Relative to settings file
  ]
}

Path Resolution:

  • //path = Absolute filesystem path
  • ~/path = Home directory
  • /path = Relative to settings file location
  • path or ./path = Relative to current working directory

MCP Server Configuration

{
  "mcpServers": {
    "server_name": {
      "type": "stdio|http|sse",
      "command": "command to run",
      "args": ["arg1", "arg2"],
      "env": {
        "VAR": "value"
      }
    }
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory"],
  "disabledMcpjsonServers": ["fs"]
}

API Configuration

Claude API (Anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx"
  }
}

AWS Bedrock

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1"
  }
}

Google Vertex AI

{
  "env": {
    "CLAUDE_CODE_USE_VERTEX": "1",
    "VERTEX_REGION": "us-central1"
  }
}

Dynamic API Key Helper

{
  "apiKeyHelper": "/path/to/generate_api_key.sh",
  "env": {
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "300000"
  }
}

Model Selection

Available Aliases

AliasBehavior
defaultAccount-optimized model
sonnetLatest Sonnet (4.5)
opusOpus 4.5
haikuFast Haiku model
sonnet[1m]Sonnet with 1M context
opusplanOpus→Sonnet hybrid

Switching Models

# Start with specific model
claude --model opus

# Switch during session
/model sonnet

# Check current model
/status

Sandbox Configuration

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Plugin Configuration

{
  "enabledPlugins": {
    "formatter@team-tools": true,
    "deployer@team-tools": false
  },
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins",
        "ref": "main"
      }
    }
  }
}

Sources

Rules

Previous Page

Slash Commands and Skills

Next Page

On this page

Claude Code Settings and ConfigurationSettings File HierarchySystem-Level Managed LocationsCore SettingsAdvanced SettingsEnvironment VariablesAuthenticationModel SelectionOutput and ContextMCP ConfigurationFeature FlagsWebFetch Preflight CheckDisabling the Preflight CheckSecurity ConsiderationsReferencesPermission SystemPermission ModesPermission StructureRule PatternsMCP Server ConfigurationAPI ConfigurationClaude API (Anthropic)AWS BedrockGoogle Vertex AIDynamic API Key HelperModel SelectionAvailable AliasesSwitching ModelsSandbox ConfigurationPlugin ConfigurationSources