Environment Variables Reference - Complete Claude Code Configuration Guide

Claude Code provides a series of environment variables to fine-tune its behavior. This reference handbook organizes all available environment variables for your configuration needs.

Debugging and Diagnostics

Core Debug Variables

Variable	Default	Description
`CLAUDE_CODE_DEBUG`	unset	Enable debug mode, output detailed logs
`CLAUDE_CODE_DEBUG_TOOLS`	unset	Enable tool call debugging
`CLAUDE_CODE_DEBUG_HTTP`	unset	Enable HTTP request debugging
`CLAUDE_CODE_DUMP_AUTO_MODE`	unset	Export YOLO classifier input/output for debugging permission decisions
`DEBUG`	unset	General debug switch, affects dependency libraries

Variable	Default	Description
`CLAUDE_CODE_LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`
`CLAUDE_CODE_LOG_FILE`	unset	Log file path, default outputs to console
`CLAUDE_CODE_LOG_TIMESTAMPS`	`true`	Whether to include timestamps in logs

API and Models

API Configuration

Variable	Default	Description
`ANTHROPIC_API_KEY`	unset	Anthropic API key
`CLAUDE_CODE_API_KEY`	unset	Dedicated API key (higher priority than ANTHROPIC_API_KEY)
`CLAUDE_CODE_API_BASE_URL`	`https://api.anthropic.com`	API base URL
`CLAUDE_CODE_MODEL`	`claude-sonnet-4-6`	Default model to use
`CLAUDE_CODE_MAX_TOKENS`	`8192`	Maximum output tokens

Model-Specific Configuration

Variable	Default	Description
`CLAUDE_CODE_EFFORT_LEVEL`	unset	Reasoning effort level: `low`, `medium`, `high`, `max`
`CLAUDE_CODE_FAST_MODE`	unset	Whether to enable Fast Mode
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`	`false`	Whether to disable adaptive thinking
`MAX_THINKING_TOKENS`	unset	Maximum tokens for thinking mode

Third-Party Providers

Variable	Default	Description
`AWS_ACCESS_KEY_ID`	unset	AWS Bedrock access key
`AWS_SECRET_ACCESS_KEY`	unset	AWS Bedrock secret key
`AWS_REGION`	unset	AWS region
`GOOGLE_APPLICATION_CREDENTIALS`	unset	Google Vertex AI credentials path
`GOOGLE_CLOUD_PROJECT`	unset	Google Cloud project ID

Context and Cache

Cache Control

Variable	Default	Description
`CLAUDE_CODE_CACHE_ENABLED`	`true`	Whether to enable prompt caching
`CLAUDE_CODE_CACHE_TTL`	`3600`	Cache TTL (seconds), default 1 hour
`CLAUDE_CODE_DISABLE_PROMPT_CACHE`	`false`	Completely disable prompt caching
`CLAUDE_CODE_DISABLE_CACHE_EDITING`	`false`	Disable cache editing feature

Compaction Configuration

Variable	Default	Description
`CLAUDE_CODE_DISABLE_AUTO_COMPACT`	`false`	Disable auto compaction
`CLAUDE_CODE_COMPACT_THRESHOLD`	`150000`	Auto compaction trigger threshold (tokens)
`CLAUDE_CODE_COMPACT_MIN_MESSAGES`	`10`	Minimum message count to trigger compaction

Token Budget

Variable	Default	Description
`CLAUDE_CODE_MAX_CONTEXT_TOKENS`	`200000`	Maximum context tokens
`CLAUDE_CODE_OUTPUT_TOKEN_RESERVE`	`8192`	Output token reserve
`CLAUDE_CODE_TOKEN_BUFFER`	`10000`	Token buffer

Permissions and Security

Permission Modes

Variable	Default	Description
`CLAUDE_CODE_PERMISSION_MODE`	`default`	Permission mode: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`
`CLAUDE_CODE_DISABLE_PERMISSIONS`	`false`	Disable permission checks (dangerous)
`CLAUDE_CODE_YOLO_ENABLED`	`true`	Whether to enable YOLO classifier
`CLAUDE_CODE_YOLO_DISABLED`	`false`	Completely disable YOLO classifier

Security Settings

Variable	Default	Description
`CLAUDE_CODE_DISABLE_BASH_SANDBOX`	`false`	Disable Bash sandbox (dangerous)
`CLAUDE_CODE_ALLOW_DANGEROUS_COMMANDS`	`false`	Allow dangerous commands (like rm -rf /)
`CLAUDE_CODE_DISABLE_GIT_SAFETY`	`false`	Disable Git safety protocol (dangerous)

Memory System

Memory Control

Variable	Default	Description
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	`false`	Disable automatic memory extraction
`CLAUDE_CODE_DISABLE_AUTO_DREAM`	`false`	Disable overnight memory consolidation
`CLAUDE_COWORK_MEMORY_PATH_OVERRIDE`	unset	Override memory directory path
`CLAUDE_CODE_MEMORY_LOG_LEVEL`	`info`	Memory system log level

Session Memory

Variable	Default	Description
`CLAUDE_CODE_SESSION_MEMORY_ENABLED`	`true`	Whether to enable Session Memory
`CLAUDE_CODE_SESSION_MEMORY_THRESHOLD`	`10000`	Session Memory trigger threshold (tokens)

Skills System

Variable	Default	Description
`CLAUDE_CODE_SKILLS_ENABLED`	`true`	Whether to enable skills system
`CLAUDE_CODE_SKILL_PATH`	unset	Custom skills search path
`CLAUDE_CODE_DISABLE_BUILTIN_SKILLS`	`false`	Disable built-in skills
`CLAUDE_CODE_SKILL_BUDGET_PERCENT`	`1`	Percentage of context for skills list

Agent System

Variable	Default	Description
`CLAUDE_CODE_DISABLE_SUBAGENTS`	`false`	Disable sub-agent functionality
`CLAUDE_CODE_MAX_CONCURRENT_AGENTS`	`5`	Maximum concurrent agents
`CLAUDE_CODE_AGENT_TIMEOUT`	`300`	Agent timeout (seconds)

Feature Flags

Experimental Features

Variable	Default	Description
`CLAUDE_CODE_COORDINATOR_MODE`	`false`	Enable coordinator mode
`CLAUDE_CODE_EXPERIMENTAL_SKILLS`	`false`	Enable experimental skills
`CLAUDE_CODE_VOICE_ENABLED`	`false`	Enable voice input
`CLAUDE_CODE_ALWAYS_THINKING`	`false`	Always enable thinking mode

KAIROS Mode

Variable	Default	Description
`CLAUDE_CODE_KAIROS_ENABLED`	`false`	Enable KAIROS background mode
`CLAUDE_CODE_KAIROS_TICK_INTERVAL`	`60000`	Tick interval (milliseconds)
`CLAUDE_CODE_KAIROS_CHANNELS`	unset	Enable channels list

Session Management

Variable	Default	Description
`CLAUDE_CODE_SESSION_ID`	auto-generated	Custom session ID
`CLAUDE_CODE_RESUME_SESSION`	`false`	Resume last session
`CLAUDE_CODE_DISABLE_TRANSCRIPT`	`false`	Disable session recording
`CLAUDE_CODE_TRANSCRIPT_PATH`	unset	Custom session recording path

Git and Version Control

Variable	Default	Description
`CLAUDE_CODE_GIT_ENABLED`	`true`	Enable Git integration
`CLAUDE_CODE_AUTO_COMMIT`	`false`	Auto commit changes
`CLAUDE_CODE_COMMIT_MESSAGE_STYLE`	`conventional`	Commit message style
`CLAUDE_CODE_DISABLE_PRE_COMMIT_HOOKS`	`false`	Disable pre-commit hooks

Network and Proxy

Variable	Default	Description
`HTTP_PROXY`	unset	HTTP proxy address
`HTTPS_PROXY`	unset	HTTPS proxy address
`NO_PROXY`	unset	Proxy bypass list
`CLAUDE_CODE_TIMEOUT`	`120`	Request timeout (seconds)
`CLAUDE_CODE_RETRY_ATTEMPTS`	`3`	Retry attempts

User Type

Variable	Default	Description
`USER_TYPE`	`external`	User type: `ant` (internal), `external` (external)
`CLAUDE_CODE_ORG_ID`	unset	Organization ID

Quick Configuration Examples

Debug Mode

# Enable full debugging
export CLAUDE_CODE_DEBUG=1
export CLAUDE_CODE_LOG_LEVEL=debug
export CLAUDE_CODE_DUMP_AUTO_MODE=1

claude

High Performance Mode

# Maximize performance
export CLAUDE_CODE_EFFORT_LEVEL=low
export CLAUDE_CODE_FAST_MODE=1
export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=true

claude

Safe Mode

# Most conservative security settings
export CLAUDE_CODE_PERMISSION_MODE=default
export CLAUDE_CODE_YOLO_DISABLED=1
export CLAUDE_CODE_DISABLE_BASH_SANDBOX=false

claude

Development Debug Mode

# Use during development
export CLAUDE_CODE_DEBUG=1
export CLAUDE_CODE_DISABLE_AUTO_COMPACT=true  # Convenient to view full context
export CLAUDE_CODE_DUMP_AUTO_MODE=1          # Debug permission decisions
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true   # Avoid memory interference

claude

CI/CD Mode

# For automation scripts
export CLAUDE_CODE_PERMISSION_MODE=auto
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true
export CLAUDE_CODE_NON_INTERACTIVE=1
export CLAUDE_CODE_LOG_LEVEL=error

claude --command "..."

Configuration Priority

Environment variables > Local settings > User settings > Defaults

Environment Variables (highest priority)
    ↓
.claude/settings.local.json (project-level)
    ↓
~/.claude/settings.json (user-level)
    ↓
Built-in defaults (lowest priority)

Important Notes

Sensitive Information

The following variables contain sensitive information, avoid committing to version control:

ANTHROPIC_API_KEY
AWS_SECRET_ACCESS_KEY
GOOGLE_APPLICATION_CREDENTIALS

Recommendations:

Use .env file and exclude in .gitignore
Or use system’s environment variable management tools

Dangerous Settings

The following settings bypass security mechanisms, only use when fully understanding the risks:

CLAUDE_CODE_DISABLE_PERMISSIONS=true
CLAUDE_CODE_ALLOW_DANGEROUS_COMMANDS=true
CLAUDE_CODE_DISABLE_GIT_SAFETY=true

Performance Tradeoffs

Some settings are tradeoffs between performance and quality:

EFFORT_LEVEL=low: Faster but shallower
FAST_MODE=1: Uses stronger models but higher cost
DISABLE_AUTO_COMPACT=true: Full context but reaches limits faster

Troubleshooting

Problem: Frequent Permission Prompts

# Check current permission mode
export CLAUDE_CODE_PERMISSION_MODE=auto

# Or check YOLO classifier logs
export CLAUDE_CODE_DUMP_AUTO_MODE=1

Problem: Cache Not Working

# Check cache status
export CLAUDE_CODE_DEBUG=1

# Confirm cache not disabled
unset CLAUDE_CODE_DISABLE_PROMPT_CACHE

Problem: Memory Not Working

# Check memory directory
ls ~/.claude/projects/$(basename $(git rev-parse --show-toplevel))/memory/

# Enable memory debugging
export CLAUDE_CODE_MEMORY_LOG_LEVEL=debug

This environment variables reference covers Claude Code’s main configuration options. Most users don’t need to modify these settings, but in specific scenarios (debugging, CI/CD, performance tuning), these variables give you better control over Claude Code’s behavior.

Debugging and Diagnostics#

Core Debug Variables#

Logging Related#

API and Models#

API Configuration#

Model-Specific Configuration#

Third-Party Providers#

Context and Cache#

Cache Control#

Compaction Configuration#

Token Budget#

Permissions and Security#

Permission Modes#

Security Settings#

Memory System#

Memory Control#

Session Memory#

Skills System#

Agent System#

Feature Flags#

Experimental Features#

KAIROS Mode#

Session Management#

Git and Version Control#

Network and Proxy#

User Type#

Quick Configuration Examples#

Debug Mode#

High Performance Mode#

Safe Mode#

Development Debug Mode#

CI/CD Mode#

Configuration Priority#

Important Notes#

Sensitive Information#

Dangerous Settings#

Performance Tradeoffs#

Troubleshooting#

Problem: Frequent Permission Prompts#

Problem: Cache Not Working#

Problem: Memory Not Working#