wild-cloud/ai_context/claude_code/CLAUDE_CODE_SETTINGS.md

Claude Code settings

Configure Claude Code with global and project-level settings, and environment variables.

Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the /config command when using the interactive REPL.

Settings files

The settings.json file is our official mechanism for configuring Claude Code through hierarchical settings:

• User settings are defined in ~/.claude/settings.json and apply to all projects.
• Project settings are saved in your project directory:
  • .claude/settings.json for settings that are checked into source control and shared with your team
  • .claude/settings.local.json for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore .claude/settings.local.json when it is created.
• For enterprise deployments of Claude Code, we also support enterprise managed policy settings. These take precedence over user and project settings. System administrators can deploy policies to:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux and WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

Available settings

settings.json supports a number of options:

Key	Description	Example
apiKeyHelper	Custom script, to be executed in /bin/sh, to generate an auth value. This value will be sent as X-Api-Key and Authorization: Bearer headers for model requests	/bin/generate_temp_api_key.sh
cleanupPeriodDays	How long to locally retain chat transcripts based on last activity date (default: 30 days)	20
env	Environment variables that will be applied to every session	{"FOO": "bar"}
includeCoAuthoredBy	Whether to include the co-authored-by Claude byline in git commits and pull requests (default: true)	false
permissions	See table below for structure of permissions.
hooks	Configure custom commands to run before or after tool executions. See hooks documentation	{"PreToolUse": {"Bash": "echo 'Running command...'"}}
model	Override the default model to use for Claude Code	"claude-3-5-sonnet-20241022"
statusLine	Configure a custom status line to display context. See statusLine documentation	{"type": "command", "command": "~/.claude/statusline.sh"}
forceLoginMethod	Use claudeai to restrict login to Claude.ai accounts, console to restrict login to Anthropic Console (API usage billing) accounts	claudeai
enableAllProjectMcpServers	Automatically approve all MCP servers defined in project .mcp.json files	true
enabledMcpjsonServers	List of specific MCP servers from .mcp.json files to approve	["memory", "github"]
disabledMcpjsonServers	List of specific MCP servers from .mcp.json files to reject	["filesystem"]
awsAuthRefresh	Custom script that modifies the .aws directory (see advanced credential configuration)	aws sso login --profile myprofile
awsCredentialExport	Custom script that outputs JSON with AWS credentials (see advanced credential configuration)	/bin/generate_aws_grant.sh

Permission settings

Keys	Description	Example
allow	Array of permission rules to allow tool use	[ "Bash(git diff:*)" ]
ask	Array of permission rules to ask for confirmation upon tool use.	[ "Bash(git push:*)" ]
deny	Array of permission rules to deny tool use. Use this to also exclude sensitive files from Claude Code access.	[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectories	Additional working directories that Claude has access to	[ "../docs/" ]
defaultMode	Default permission mode when opening Claude Code	"acceptEdits"
disableBypassPermissionsMode	Set to "disable" to prevent bypassPermissions mode from being activated. See managed policy settings	"disable"

Settings precedence

Settings are applied in order of precedence (highest to lowest):

1. Enterprise managed policies (managed-settings.json)

   • Deployed by IT/DevOps
   • Cannot be overridden

2. Command line arguments

   • Temporary overrides for a specific session

3. Local project settings (.claude/settings.local.json)

   • Personal project-specific settings

4. Shared project settings (.claude/settings.json)

   • Team-shared project settings in source control

5. User settings (~/.claude/settings.json)

   • Personal global settings

This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

Key points about the configuration system

• Memory files (CLAUDE.md): Contain instructions and context that Claude loads at startup
• Settings files (JSON): Configure permissions, environment variables, and tool behavior
• Slash commands: Custom commands that can be invoked during a session with /command-name
• MCP servers: Extend Claude Code with additional tools and integrations
• Precedence: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
• Inheritance: Settings are merged, with more specific settings adding to or overriding broader ones

System prompt availability

Unlike for claude.ai, we do not publish Claude Code's internal system prompt on this website. Use CLAUDE.md files or `--append-system-prompt` to add custom instructions to Claude Code's behavior.

Excluding sensitive files

To prevent Claude Code from accessing files containing sensitive information (e.g., API keys, secrets, environment files), use the permissions.deny setting in your .claude/settings.json file:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

This replaces the deprecated ignorePatterns configuration. Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.

Subagent configuration

Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:

• User subagents: ~/.claude/agents/ - Available across all your projects
• Project subagents: .claude/agents/ - Specific to your project and can be shared with your team

Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the subagents documentation.

Environment variables

Claude Code supports the following environment variables to control its behavior:

All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.

Variable	Purpose
ANTHROPIC_API_KEY	API key sent as X-Api-Key header, typically for the Claude SDK (for interactive usage, run /login)
ANTHROPIC_AUTH_TOKEN	Custom value for the Authorization header (the value you set here will be prefixed with Bearer )
ANTHROPIC_CUSTOM_HEADERS	Custom headers you want to add to the request (in Name: Value format)
ANTHROPIC_MODEL	Name of custom model to use (see Model Configuration)
ANTHROPIC_SMALL_FAST_MODEL	Name of Haiku-class model for background tasks
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	Override AWS region for the small/fast model when using Bedrock
AWS_BEARER_TOKEN_BEDROCK	Bedrock API key for authentication (see Bedrock API keys)
BASH_DEFAULT_TIMEOUT_MS	Default timeout for long-running bash commands
BASH_MAX_TIMEOUT_MS	Maximum timeout the model can set for long-running bash commands
BASH_MAX_OUTPUT_LENGTH	Maximum number of characters in bash outputs before they are middle-truncated
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR	Return to the original working directory after each Bash command
CLAUDE_CODE_API_KEY_HELPER_TTL_MS	Interval in milliseconds at which credentials should be refreshed (when using apiKeyHelper)
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL	Skip auto-installation of IDE extensions
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Set the maximum number of output tokens for most requests
CLAUDE_CODE_USE_BEDROCK	Use Bedrock
CLAUDE_CODE_USE_VERTEX	Use Vertex
CLAUDE_CODE_SKIP_BEDROCK_AUTH	Skip AWS authentication for Bedrock (e.g. when using an LLM gateway)
CLAUDE_CODE_SKIP_VERTEX_AUTH	Skip Google authentication for Vertex (e.g. when using an LLM gateway)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY
CLAUDE_CODE_DISABLE_TERMINAL_TITLE	Set to 1 to disable automatic terminal title updates based on conversation context
DISABLE_AUTOUPDATER	Set to 1 to disable automatic updates. This takes precedence over the autoUpdates configuration setting.
DISABLE_BUG_COMMAND	Set to 1 to disable the /bug command
DISABLE_COST_WARNINGS	Set to 1 to disable cost warning messages
DISABLE_ERROR_REPORTING	Set to 1 to opt out of Sentry error reporting
DISABLE_NON_ESSENTIAL_MODEL_CALLS	Set to 1 to disable model calls for non-critical paths like flavor text
DISABLE_TELEMETRY	Set to 1 to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands)
HTTP_PROXY	Specify HTTP proxy server for network connections
HTTPS_PROXY	Specify HTTPS proxy server for network connections
MAX_THINKING_TOKENS	Force a thinking for the model budget
MCP_TIMEOUT	Timeout in milliseconds for MCP server startup
MCP_TOOL_TIMEOUT	Timeout in milliseconds for MCP tool execution
MAX_MCP_OUTPUT_TOKENS	Maximum number of tokens allowed in MCP tool responses (default: 25000)
USE_BUILTIN_RIPGREP	Set to 1 to ignore system-installed rg and use rg included with Claude Code
VERTEX_REGION_CLAUDE_3_5_HAIKU	Override region for Claude 3.5 Haiku when using Vertex AI
VERTEX_REGION_CLAUDE_3_5_SONNET	Override region for Claude Sonnet 3.5 when using Vertex AI
VERTEX_REGION_CLAUDE_3_7_SONNET	Override region for Claude 3.7 Sonnet when using Vertex AI
VERTEX_REGION_CLAUDE_4_0_OPUS	Override region for Claude 4.0 Opus when using Vertex AI
VERTEX_REGION_CLAUDE_4_0_SONNET	Override region for Claude 4.0 Sonnet when using Vertex AI
VERTEX_REGION_CLAUDE_4_1_OPUS	Override region for Claude 4.1 Opus when using Vertex AI

Configuration options

To manage your configurations, use the following commands:

• List settings: claude config list
• See a setting: claude config get <key>
• Change a setting: claude config set <key> <value>
• Push to a setting (for lists): claude config add <key> <value>
• Remove from a setting (for lists): claude config remove <key> <value>

By default config changes your project configuration. To manage your global configuration, use the --global (or -g) flag.

Global configuration

To set a global configuration, use claude config set -g <key> <value>:

Key	Description	Example
autoUpdates	Whether to enable automatic updates (default: true). When enabled, Claude Code automatically downloads and installs updates in the background. Updates are applied when you restart Claude Code.	false
preferredNotifChannel	Where you want to receive notifications (default: iterm2)	iterm2, iterm2_with_bell, terminal_bell, or notifications_disabled
theme	Color theme	dark, light, light-daltonized, or dark-daltonized
verbose	Whether to show full bash and command outputs (default: false)	true

Tools available to Claude

Claude Code has access to a set of powerful tools that help it understand and modify your codebase:

Tool	Description	Permission Required
Bash	Executes shell commands in your environment	Yes
Edit	Makes targeted edits to specific files	Yes
Glob	Finds files based on pattern matching	No
Grep	Searches for patterns in file contents	No
LS	Lists files and directories	No
MultiEdit	Performs multiple edits on a single file atomically	Yes
NotebookEdit	Modifies Jupyter notebook cells	Yes
NotebookRead	Reads and displays Jupyter notebook contents	No
Read	Reads the contents of files	No
Task	Runs a sub-agent to handle complex, multi-step tasks	No
TodoWrite	Creates and manages structured task lists	No
WebFetch	Fetches content from a specified URL	Yes
WebSearch	Performs web searches with domain filtering	Yes
Write	Creates or overwrites files	Yes

Permission rules can be configured using /allowed-tools or in permission settings.

Extending tools with hooks

You can run custom commands before or after any tool executes using Claude Code hooks.

For example, you could automatically run a Python formatter after Claude modifies Python files, or prevent modifications to production configuration files by blocking Write operations to certain paths.

See also

• Identity and Access Management - Learn about Claude Code's permission system
• IAM and access control - Enterprise policy management
• Troubleshooting - Solutions for common configuration issues