Claude code env variables

ENVIRONMENT_VARIABLES.md

Claude Code Environment Variables Reference

This document outlines all supported environment variables in Claude Code, organized by category.

Table of Contents

1. API & Authentication
2. Model Configuration
3. Network & Proxy
4. Performance & Optimization
5. Debugging & Logging
6. Feature Flags
7. Remote & Cloud Deployment
8. File & Path Configuration
9. Shell & Terminal
10. Security & Permissions
11. Telemetry & Analytics
12. Development & Testing

---

API & Authentication

ANTHROPIC_API_KEY

API key for authenticating with Anthropic's API. Takes precedence over OAuth when set.

• Type: String
• Example: sk-ant-xxxxx

ANTHROPIC_AUTH_TOKEN

Alternative authentication token for API requests.

• Type: String
• Priority: Lower than ANTHROPIC_API_KEY

ANTHROPIC_BASE_URL

Custom base URL for API requests. Allows routing to different API endpoints.

• Type: URL
• Default: https://api.anthropic.com
• Example: https://api-staging.anthropic.com

CLAUDE_CODE_OAUTH_TOKEN

OAuth token for session authentication. Used in remote sessions and CCR environments.

• Type: String

CLAUDE_CODE_OAUTH_REFRESH_TOKEN

Refresh token for OAuth sessions. Enables automatic token refresh.

• Type: String

CLAUDE_CODE_OAUTH_SCOPES

Comma-separated list of OAuth scopes requested during authentication.

• Type: String (comma-separated)
• Example: read,write,admin

CLAUDE_CODE_OAUTH_CLIENT_ID

Custom OAuth client ID override (e.g., for Xcode integration).

• Type: String

CLAUDE_CODE_SESSION_ACCESS_TOKEN

Direct session access token for remote environments.

• Type: String

CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR

File descriptor for WebSocket authentication token in remote sessions.

• Type: Integer (file descriptor)

---

Model Configuration

ANTHROPIC_MODEL

Override the default model used for chat and queries.

• Type: String
• Examples: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5

ANTHROPIC_DEFAULT_OPUS_MODEL

Custom Opus model for deployments. Sets the Opus option in model selection.

• Type: String

ANTHROPIC_DEFAULT_SONNET_MODEL

Custom Sonnet model for deployments.

• Type: String

ANTHROPIC_DEFAULT_HAIKU_MODEL

Custom Haiku model for deployments.

• Type: String

ANTHROPIC_SMALL_FAST_MODEL

Override the small/fast model used for quick operations.

• Type: String
• Default: Haiku model

ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION

AWS region for Bedrock's small/fast model.

• Type: String
• Example: us-east-1

ANTHROPIC_CUSTOM_MODEL_OPTION

Define a custom model option not in the standard list.

• Type: String

ANTHROPIC_CUSTOM_MODEL_OPTION_NAME

Display name for custom model option.

• Type: String

ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION

Description for custom model option.

• Type: String

MAX_THINKING_TOKENS

Maximum tokens allocated for extended thinking during API calls.

• Type: Integer
• Example: 10000

CLAUDE_CODE_DISABLE_THINKING

Disable extended thinking feature globally.

• Type: Boolean (0 or 1)

CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING

Disable adaptive thinking mode that adjusts token allocation.

• Type: Boolean

DISABLE_INTERLEAVED_THINKING

Disable interleaved thinking (thinking blocks between tool calls).

• Type: Boolean

CLAUDE_CODE_EFFORT_LEVEL

Set effort level for processing (low, medium, high, max). Numeric values (ant-only).

• Type: String or Integer

CLAUDE_CODE_ALWAYS_ENABLE_EFFORT

Always enable effort setting even when not normally available.

• Type: Boolean

---

Network & Proxy

HTTP_PROXY / http_proxy

HTTP proxy server URL for outgoing requests.

• Type: URL
• Example: http://proxy.example.com:8080

HTTPS_PROXY / https_proxy

HTTPS proxy server URL for outgoing requests.

• Type: URL

NO_PROXY / no_proxy

Comma-separated list of hosts/domains to bypass proxy.

• Type: String (comma-separated)
• Example: localhost,127.0.0.1,*.example.com

ANTHROPIC_UNIX_SOCKET

Unix socket path for direct socket communication with API.

• Type: Path
• Use Case: Local development, special deployments

NODE_EXTRA_CA_CERTS

Path to additional CA certificate file for SSL/TLS validation.

• Type: File path
• Use Case: Corporate proxies, custom certificate authorities

CLAUDE_CODE_CLIENT_CERT

Path to client certificate for mTLS authentication.

• Type: File path
• Format: PEM

CLAUDE_CODE_CLIENT_KEY

Path to client private key for mTLS authentication.

• Type: File path
• Format: PEM

CLAUDE_CODE_CLIENT_KEY_PASSPHRASE

Passphrase for encrypted client private key.

• Type: String

CLAUDE_CODE_PROXY_RESOLVES_HOSTS

Let proxy handle hostname resolution instead of local DNS.

• Type: Boolean

---

Performance & Optimization

CLAUDE_CODE_DISABLE_FAST_MODE

Disable fast mode optimization for queries.

• Type: Boolean

CLAUDE_CODE_DISABLE_PROMPT_CACHING

Disable prompt caching globally.

• Type: Boolean

DISABLE_PROMPT_CACHING_HAIKU

Disable prompt caching specifically for Haiku model.

• Type: Boolean

DISABLE_PROMPT_CACHING_SONNET

Disable prompt caching specifically for Sonnet model.

• Type: Boolean

DISABLE_PROMPT_CACHING_OPUS

Disable prompt caching specifically for Opus model.

• Type: Boolean

ENABLE_PROMPT_CACHING_1H_BEDROCK

Enable 1-hour prompt caching for Bedrock deployments.

• Type: Boolean

API_TIMEOUT_MS

API request timeout in milliseconds.

• Type: Integer
• Default: 300000 (5 minutes for CLI), 120000 (2 minutes for remote)
• Example: 600000

CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING

Disable file checkpointing for undo/redo functionality.

• Type: Boolean

CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING

Enable file checkpointing in SDK mode.

• Type: Boolean

CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL

Disable virtual scrolling in terminal output (increases memory usage).

• Type: Boolean

CLAUDE_CODE_SCROLL_SPEED

Adjustment factor for scroll speed (default: 1).

• Type: Float
• Example: 1.5

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

Disable background task execution.

• Type: Boolean

---

Debugging & Logging

CLAUDE_CODE_DEBUG_LOG_LEVEL

Set minimum debug logging level (trace, debug, info, warn, error).

• Type: String
• Example: debug

DEBUG / DEBUG_SDK

Enable general debug logging.

• Type: Boolean

CLAUDE_CODE_DEBUG_LOGS_DIR

Directory for debug log files.

• Type: Directory path
• Default: ~/.claude/debug/

CLAUDE_CODE_DIAGNOSTICS_FILE

Path to write diagnostic information.

• Type: File path

CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER

Exit immediately after first render (performance testing).

• Type: Boolean
• Ant-only: Yes

CLAUDE_CODE_PROFILE_STARTUP

Enable detailed startup performance profiling.

• Type: Boolean

CLAUDE_CODE_PROFILE_QUERY

Enable query execution profiling.

• Type: Boolean

CLAUDE_CODE_FRAME_TIMING_LOG

Log frame timing information to file.

• Type: File path

CLAUDE_CODE_PERFETTO_TRACE

Enable Perfetto trace output for performance analysis.

• Type: Boolean

CLAUDE_CODE_PERFETTO_WRITE_INTERVAL_S

Interval for writing Perfetto trace data (seconds).

• Type: Integer

CLAUDE_CODE_TERMINAL_RECORDING

Enable terminal session recording (asciicast format).

• Type: Boolean
• Ant-only: Yes

CLAUDE_CODE_DUMP_AUTO_MODE

Dump auto mode classifier outputs for debugging.

• Type: Boolean
• Ant-only: Yes

---

Feature Flags

CLAUDE_CODE_SIMPLE

Run in simple mode with limited tools (Bash, Read, Edit only).

• Type: Boolean
• Use Case: Restricted environments, testing

CLAUDE_CODE_BRIEF

Enable brief/compact output mode.

• Type: Boolean

CLAUDE_CODE_STREAMLINED_OUTPUT

Enable streamlined output format.

• Type: Boolean

CLAUDE_CODE_DISABLE_THINKING

Globally disable extended thinking.

• Type: Boolean

CLAUDE_CODE_DISABLE_AUTO_MEMORY

Disable automatic memory generation.

• Type: Boolean

CLAUDE_CODE_DISABLE_AUTO_COMPACT

Disable automatic context compaction.

• Type: Boolean

DISABLE_COMPACT

Disable all compaction (manual and automatic).

• Type: Boolean

CLAUDE_CODE_AUTO_COMPACT_WINDOW

Configure auto-compaction triggering window.

• Type: String or JSON

CLAUDE_CODE_DISABLE_ATTACHMENTS

Disable file attachment support.

• Type: Boolean

CLAUDE_CODE_DISABLE_ADVISOR_TOOL

Disable the advisor tool.

• Type: Boolean

CLAUDE_CODE_DISABLE_TERMINAL_TITLE

Don't update terminal window title.

• Type: Boolean

CLAUDE_CODE_DISABLE_MOUSE

Disable mouse support in terminal.

• Type: Boolean

CLAUDE_CODE_DISABLE_MOUSE_CLICKS

Disable mouse click handling.

• Type: Boolean

CLAUDE_CODE_NO_FLICKER

Prevent screen flicker (alt-screen mode). Override auto-detection.

• Type: Boolean
• Default: Auto-detect based on terminal

CLAUDE_CODE_DISABLE_1M_CONTEXT

Disable 1M context window usage.

• Type: Boolean

CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS

Disable git-related instructions.

• Type: Boolean

CLAUDE_CODE_ACCESSIBILITY

Enable accessibility features (screen reader mode).

• Type: Boolean

CLAUDE_CODE_DISABLE_MESSAGE_ACTIONS

Disable message action buttons.

• Type: Boolean

CLAUDE_CODE_BRIEF_UPLOAD

Enable brief mode upload functionality.

• Type: Boolean

---

Remote & Cloud Deployment

CLAUDE_CODE_REMOTE

Indicate running in remote/cloud environment (CCR).

• Type: Boolean

CLAUDE_CODE_REMOTE_SESSION_ID

Session ID for remote environment.

• Type: String (UUID)

CLAUDE_CODE_REMOTE_MEMORY_DIR

Directory for storing session memory in remote environments.

• Type: Directory path

CLAUDE_CODE_REMOTE_ENVIRONMENT_TYPE

Type of remote environment (e.g., 'bridge', 'byoc').

• Type: String

SESSION_INGRESS_URL

URL for session ingress endpoint in remote mode.

• Type: URL

CLAUDE_CODE_SESSION_INGRESS_URL

Override for session ingress URL.

• Type: URL

CLAUDE_CODE_BRIDGE_OAUTH_TOKEN

OAuth token for bridge-based remote sessions.

• Type: String
• Ant-only: Yes

CLAUDE_CODE_BRIDGE_BASE_URL

Base URL for bridge service.

• Type: URL
• Ant-only: Yes

CLAUDE_CODE_USE_CCR_V2

Use CCR v2 (newer cloud runtime version).

• Type: Boolean

CCR_FORCE_BUNDLE

Force code bundling in CCR environments.

• Type: Boolean

CCR_ENABLE_BUNDLE

Enable code bundling in CCR.

• Type: Boolean

CCR_UPSTREAM_PROXY_ENABLED

Enable upstream proxy in CCR.

• Type: Boolean

CLAUDE_CODE_ENVIRONMENT_KIND

Kind of deployment environment (bridge, byoc, anthropic_cloud).

• Type: String

CLAUDE_CODE_ENVIRONMENT_RUNNER_VERSION

Version of the environment runner.

• Type: String

CLAUDE_CODE_ENVIRONMENT_RUNNER_VERSION

Dynamically detected environment runner version.

• Type: String

CLAUDE_CODE_CONTAINER_ID

Unique identifier for container instance.

• Type: String (UUID)

CLAUDE_CODE_COWORKER_TYPE

Type of coworker in team environment.

• Type: String

ENABLE_SESSION_PERSISTENCE

Enable session persistence across restarts.

• Type: Boolean

CLAUDE_CODE_SKIP_PROMPT_HISTORY

Skip saving prompt history in persistent sessions.

• Type: Boolean

---

File & Path Configuration

CLAUDE_CONFIG_DIR

Directory for Claude configuration and cache files.

• Type: Directory path
• Default: ~/.claude

CLAUDE_CODE_TMPDIR

Temporary directory for Claude Code operations.

• Type: Directory path
• Default: /tmp (Unix) or %TEMP% (Windows)

CLAUDE_CODE_PLUGIN_CACHE_DIR

Custom directory for plugin cache.

• Type: Directory path

CLAUDE_CODE_PLUGIN_SEED_DIR

Directory containing seed plugins.

• Type: Directory path

CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS

Timeout for plugin git operations.

• Type: Integer (milliseconds)

CLAUDE_CODE_USE_COWORK_PLUGINS

Use Cowork plugin directory instead of standard.

• Type: Boolean

XDG_CONFIG_HOME

XDG standard config directory (Linux/macOS).

• Type: Directory path
• Default: ~/.config

APPDATA

Windows application data directory.

• Type: Directory path (Windows)

LOCALAPPDATA

Windows local application data directory.

• Type: Directory path (Windows)

---

Shell & Terminal

SHELL

User's shell executable path.

• Type: Path
• Examples: /bin/bash, /bin/zsh

CLAUDE_CODE_SHELL

Override shell for Claude Code operations.

• Type: Path

CLAUDE_CODE_SHELL_PREFIX

Command prefix for shell operations (e.g., for shell prefix commands).

• Type: String

CLAUDE_CODE_USE_POWERSHELL_TOOL

Enable PowerShell tool (Windows).

• Type: Boolean
• Default: Auto-detect

CLAUDE_CODE_MAINTAIN_PROJECT_WORKING_DIR

Maintain project working directory across commands.

• Type: Boolean

TERM

Terminal type (affects color and feature support).

• Type: String
• Examples: xterm-256color, screen, tmux

TERM_PROGRAM

Terminal program identifier (auto-detected).

• Type: String
• Examples: iTerm.app, vscode, tmux

TMUX

Indicates running inside tmux session.

• Type: String
• Set by: tmux automatically

ITERM_SESSION_ID

iTerm2 session identifier.

• Type: String

CLAUDE_CODE_TMUX_SESSION

Name of tmux session for Claude Code.

• Type: String

CLAUDE_CODE_TMUX_PREFIX

Tmux prefix key configuration.

• Type: String

CLAUDE_CODE_TMUX_TRUECOLOR

Enable truecolor in tmux.

• Type: Boolean

CLAUDE_CODE_TMUX_PREFIX_CONFLICTS

Indicate tmux prefix conflicts with Claude.

• Type: Boolean

---

Security & Permissions

CLAUDE_CODE_ADDITIONAL_PROTECTION

Enable additional security protections.

• Type: Boolean

CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK

Skip command injection detection (not recommended).

• Type: Boolean

CLAUDE_CODE_PERMISSION_MODE

Set permission checking mode explicitly.

• Type: String
• Options: default, accept-edits, plan, auto

CLAUDE_CODE_DISABLE_POLICY_SKILLS

Disable policy-based skill restrictions.

• Type: Boolean

CLAUDE_JOB_DIR

Directory for job templates and constraints.

• Type: Directory path

---

Telemetry & Analytics

DISABLE_TELEMETRY

Completely disable telemetry collection.

• Type: Boolean

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

Disable non-essential network traffic (essential-traffic mode).

• Type: Boolean

DISABLE_ERROR_REPORTING

Disable error reporting to Anthropic.

• Type: Boolean

CLAUDE_CODE_ENABLE_TELEMETRY

Explicitly enable telemetry (3rd party providers).

• Type: Boolean

OTEL_METRICS_EXPORTER

OpenTelemetry metrics exporter type.

• Type: String
• Examples: otlp, jaeger, prometheus

OTEL_LOGS_EXPORTER

OpenTelemetry logs exporter type.

• Type: String

OTEL_TRACES_EXPORTER

OpenTelemetry traces exporter type.

• Type: String

OTEL_EXPORTER_OTLP_ENDPOINT

OpenTelemetry OTLP exporter endpoint.

• Type: URL
• Example: http://localhost:4318

OTEL_EXPORTER_OTLP_HEADERS

Custom headers for OTLP exporter.

• Type: String (comma-separated key=value pairs)

OTEL_EXPORTER_OTLP_PROTOCOL

Protocol for OTLP exporter (http/protobuf, grpc).

• Type: String

OTEL_METRIC_EXPORT_INTERVAL

Interval for metrics export (milliseconds).

• Type: Integer

OTEL_LOGS_EXPORT_INTERVAL

Interval for logs export (milliseconds).

• Type: Integer

OTEL_TRACES_EXPORT_INTERVAL

Interval for traces export (milliseconds).

• Type: Integer

OTEL_LOG_USER_PROMPTS

Log user prompts in telemetry.

• Type: Boolean

OTEL_LOG_TOOL_DETAILS

Log detailed tool information.

• Type: Boolean

OTEL_LOG_TOOL_CONTENT

Log tool content in telemetry.

• Type: Boolean

CLAUDE_CODE_ENABLE_TELEMETRY

Enable 3rd party telemetry.

• Type: Boolean

BETA_TRACING_ENDPOINT

Endpoint for beta tracing/telemetry.

• Type: URL
• Ant-only: Yes

CLAUDE_CODE_ENHANCED_TELEMETRY_BETA

Enable enhanced telemetry beta features.

• Type: Boolean

ANT_CLAUDE_CODE_METRICS_ENDPOINT

Custom metrics endpoint for ant users.

• Type: URL
• Ant-only: Yes

---

Development & Testing

NODE_ENV

Node.js environment (development, production, test).

• Type: String
• Values: development, production, test

NODE_OPTIONS

Node.js command-line options.

• Type: String
• Example: --max-old-space-size=8192

USER_TYPE

Internal user type classification.

• Type: String
• Values: external, ant (internal)
• Note: Build-time constant, affects available features

CLAUDE_CODE_ENTRYPOINT

Type of Claude Code entry point.

• Type: String
• Values: cli, sdk-ts, sdk-py, sdk-cli, remote, claude-desktop, claude-vscode, local-agent

CLAUDE_CODE_ENTRYPOINT (detected)

Automatically determined entry point.

• Type: String

IS_DEMO

Running in demo mode (limited features).

• Type: Boolean

MONOREPO_ROOT_DIR

Root directory of monorepo.

• Type: Directory path

CLAUDE_CODE_TEST_FIXTURES_ROOT

Root directory for test fixtures.

• Type: Directory path

VCR_RECORD

Record VCR cassettes for tests.

• Type: Boolean

FORCE_VCR

Force VCR usage in tests.

• Type: Boolean

MAX_STRUCTURED_OUTPUT_RETRIES

Max retries for structured output from API.

• Type: Integer
• Default: 5

CLAUDE_CODE_MAX_OUTPUT_TOKENS

Override maximum output tokens (ant-only).

• Type: Integer

CLAUDE_CODE_MAX_RETRIES

Maximum API request retries.

• Type: Integer

DISABLE_INSTALLATION_CHECKS

Skip Claude Code installation validation.

• Type: Boolean

DISABLE_DOCTOR_COMMAND

Disable /doctor command.

• Type: Boolean

DISABLE_AUTOUPDATER

Disable auto-update functionality.

• Type: Boolean

FORCE_AUTOUPDATE_PLUGINS

Force plugin auto-updates.

• Type: Boolean

CLAUDE_CODE_OVERRIDE_DATE

Override current date for testing.

• Type: String (ISO date)
• Ant-only: Yes

CLAUDE_CODE_UNDERCOVER

Enable undercover/testing mode.

• Type: Boolean
• Ant-only: Yes

GITHUB_ACTIONS

Indicates running in GitHub Actions CI.

• Type: Boolean (auto-set)

CI

Generic CI environment indicator.

• Type: Boolean

TEST_ENABLE_SESSION_PERSISTENCE

Enable session persistence in tests.

• Type: Boolean

---

Additional Notes

Build-Time Constants

Some variables are evaluated at build time and cannot be changed at runtime:

• USER_TYPE - Build-time define, affects feature availability
• Various ANT_ prefixed variables - Ant-specific build configuration

Ant-Only Features

Features marked as Ant-only are only available in internal Anthropic builds:

• Extra debugging tools
• Internal model overrides
• Advanced telemetry options
• Undercover mode for testing

Environment Variable Priority

When multiple authentication methods are available:

1. ANTHROPIC_API_KEY (highest priority)
2. ANTHROPIC_AUTH_TOKEN
3. OAuth tokens
4. API key helper

Configuration Precedence

For settings available in multiple places:

1. Command-line flags (highest)
2. Environment variables
3. Configuration files
4. Defaults (lowest)

---

See Also

• Claude Code Documentation