claude-code/.env.example

# =============================================================================
# Claude Code CLI — Environment Variables
# =============================================================================
# Copy this file to .env and fill in the values you need.
# All variables are optional unless noted otherwise.
#
# ─── HOW AUTHENTICATION WORKS ───────────────────────────────────────────────
#
# The CLI supports multiple authentication backends, resolved in this order:
#
# 1. PROVIDER SELECTION (src/utils/model/providers.ts — getAPIProvider()):
#    Checks CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or
#    CLAUDE_CODE_USE_FOUNDRY. If set, routes to that 3rd-party provider.
#    Otherwise uses Direct Anthropic API.
#
# 2. OAUTH vs API KEY DECISION (src/utils/auth.ts — isAnthropicAuthEnabled()):
#    OAuth is DISABLED (API-key-only mode) when any of these are true:
#      - --bare flag is used (sets CLAUDE_CODE_SIMPLE=1)
#      - CLAUDE_CODE_USE_BEDROCK / VERTEX / FOUNDRY is set
#      - ANTHROPIC_API_KEY env var is set (and not in managed OAuth context)
#      - ANTHROPIC_AUTH_TOKEN env var is set
#      - An apiKeyHelper is configured in settings
#    If none of the above, OAuth is attempted via ~/.claude/.credentials.json.
#
# 3. API KEY RESOLUTION (src/utils/auth.ts — getAnthropicApiKey()):
#    Priority order when OAuth is not active:
#      a. CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR (pipe-passed key)
#      b. apiKeyHelper (configured external command in settings)
#      c. ANTHROPIC_API_KEY env var
#      d. System keychain
#      e. ~/.claude/.credentials config
#
# 4. CLIENT CONSTRUCTION (src/services/api/client.ts — getAnthropicClient()):
#    Creates the appropriate SDK client (Anthropic, Bedrock, Vertex, or
#    Foundry) using the resolved auth credentials plus any custom headers
#    from ANTHROPIC_CUSTOM_HEADERS.
#
# FOR DEVELOPMENT: The simplest path is to set ANTHROPIC_API_KEY below.
# The auth system will detect the external key and skip OAuth entirely.
# =============================================================================

# ── Authentication ───────────────────────────────────────────────────────────
# Your Anthropic API key (required for direct API access)
ANTHROPIC_API_KEY=

# Bearer auth token (alternative to API key — used by bridge/remote)
# ANTHROPIC_AUTH_TOKEN=

# Custom API base URL (default: https://api.anthropic.com)
# ANTHROPIC_BASE_URL=

# Custom headers sent with every API request (multiline, "Name: Value" per line)
# ANTHROPIC_CUSTOM_HEADERS=

# Add additional protection header to API requests
# CLAUDE_CODE_ADDITIONAL_PROTECTION=true

# Pipe-pass API key via file descriptor (advanced — for managed environments)
# CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR=

# ── Model Selection ──────────────────────────────────────────────────────────
# Override the default model
# ANTHROPIC_MODEL=

# Override the small/fast model used internally
# ANTHROPIC_SMALL_FAST_MODEL=

# Custom model overrides (name + description are optional display labels)
# ANTHROPIC_DEFAULT_OPUS_MODEL=
# ANTHROPIC_DEFAULT_OPUS_MODEL_NAME=
# ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION=
# ANTHROPIC_DEFAULT_SONNET_MODEL=
# ANTHROPIC_DEFAULT_SONNET_MODEL_NAME=
# ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION=
# ANTHROPIC_DEFAULT_HAIKU_MODEL=
# ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME=
# ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION=

# Custom model option (shown alongside built-in models)
# ANTHROPIC_CUSTOM_MODEL_OPTION=
# ANTHROPIC_CUSTOM_MODEL_OPTION_NAME=
# ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION=

# Model for sub-agents / teammates
# CLAUDE_CODE_SUBAGENT_MODEL=

# ── AWS Bedrock ──────────────────────────────────────────────────────────────
# Enable Bedrock backend (uses AWS SDK default credentials: IAM, profile, env)
# CLAUDE_CODE_USE_BEDROCK=true

# Custom Bedrock endpoint URL
# ANTHROPIC_BEDROCK_BASE_URL=

# AWS region for Bedrock (default: us-east-1)
# AWS_REGION=us-east-1
# AWS_DEFAULT_REGION=us-east-1

# Override AWS region specifically for the small fast model (Haiku)
# ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=

# Bearer token auth for Bedrock (alternative to IAM)
# AWS_BEARER_TOKEN_BEDROCK=

# Skip Bedrock auth (for testing without real AWS credentials)
# CLAUDE_CODE_SKIP_BEDROCK_AUTH=false

# ── Google Vertex AI ─────────────────────────────────────────────────────────
# Enable Vertex AI backend
# CLAUDE_CODE_USE_VERTEX=true

# Required: Your GCP project ID
# ANTHROPIC_VERTEX_PROJECT_ID=

# Default GCP region for all models
# CLOUD_ML_REGION=us-east5

# Model-specific region overrides (highest priority)
# VERTEX_REGION_CLAUDE_3_5_HAIKU=
# VERTEX_REGION_CLAUDE_HAIKU_4_5=
# VERTEX_REGION_CLAUDE_3_5_SONNET=
# VERTEX_REGION_CLAUDE_3_7_SONNET=

# Custom Vertex base URL
# ANTHROPIC_VERTEX_BASE_URL=

# GCP service account credentials JSON file
# GOOGLE_APPLICATION_CREDENTIALS=

# Skip Vertex auth (for testing without real GCP credentials)
# CLAUDE_CODE_SKIP_VERTEX_AUTH=false

# ── Azure Foundry ────────────────────────────────────────────────────────────
# Enable Azure Foundry backend
# CLAUDE_CODE_USE_FOUNDRY=true

# Azure resource name (creates URL: https://{resource}.services.ai.azure.com/...)
# ANTHROPIC_FOUNDRY_RESOURCE=

# Alternative: provide full base URL directly instead of resource name
# ANTHROPIC_FOUNDRY_BASE_URL=

# Foundry API key (if not set, uses Azure AD / DefaultAzureCredential)
# ANTHROPIC_FOUNDRY_API_KEY=

# Skip Foundry auth (for testing without real Azure credentials)
# CLAUDE_CODE_SKIP_FOUNDRY_AUTH=false

# ── Shell & Environment ─────────────────────────────────────────────────────
# Override shell used for BashTool (default: auto-detected)
# CLAUDE_CODE_SHELL=/bin/bash

# Prefix prepended to every shell command
# CLAUDE_CODE_SHELL_PREFIX=

# Override temp directory
# CLAUDE_CODE_TMPDIR=

# ── Performance & Limits ─────────────────────────────────────────────────────
# Maximum output tokens per response
# CLAUDE_CODE_MAX_OUTPUT_TOKENS=

# Maximum tokens when reading files
# CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=

# Idle timeout (minutes) before session ends (default: 75)
# CLAUDE_CODE_IDLE_THRESHOLD_MINUTES=75

# Idle token threshold (default: 100000)
# CLAUDE_CODE_IDLE_TOKEN_THRESHOLD=100000

# Node.js options (e.g. heap size)
# NODE_OPTIONS=--max-old-space-size=8192

# ── Features & Modes ────────────────────────────────────────────────────────
# Enable simplified/worker mode (also set by --bare flag)
# CLAUDE_CODE_SIMPLE=true

# Enable coordinator (multi-agent) mode
# CLAUDE_CODE_COORDINATOR_MODE=true

# Enable proactive mode
# CLAUDE_CODE_PROACTIVE=true

# Enable experimental agent teams
# CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

# Enable task management
# CLAUDE_CODE_ENABLE_TASKS=true

# Enable prompt suggestions
# CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true

# ── Accessibility & UX ──────────────────────────────────────────────────────
# Enable accessibility mode
# CLAUDE_CODE_ACCESSIBILITY=true

# Disable terminal title updates
# CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true

# Disable virtual scrolling
# CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL=true

# Streamlined output (less verbose)
# CLAUDE_CODE_STREAMLINED_OUTPUT=true

# Disable syntax highlighting
# CLAUDE_CODE_SYNTAX_HIGHLIGHT=false

# ── Remote / Bridge ─────────────────────────────────────────────────────────
# Enable remote execution mode
# CLAUDE_CODE_REMOTE=true

# Remote session ID
# CLAUDE_CODE_REMOTE_SESSION_ID=

# Environment kind (e.g. bridge)
# CLAUDE_CODE_ENVIRONMENT_KIND=

# OAuth token injected by bridge/CCR
# CLAUDE_CODE_OAUTH_TOKEN=

# OAuth refresh token for bridge
# CLAUDE_CODE_OAUTH_REFRESH_TOKEN=

# OAuth scopes
# CLAUDE_CODE_OAUTH_SCOPES=

# Session access token for remote
# CLAUDE_CODE_SESSION_ACCESS_TOKEN=

# Unix socket for SSH remote auth
# ANTHROPIC_UNIX_SOCKET=

# Entrypoint identifier (cli, mcp, remote, sdk-*, etc.)
# CLAUDE_CODE_ENTRYPOINT=cli

# ── Debugging ────────────────────────────────────────────────────────────────
# Debug log level (error, warn, info, debug, trace)
# CLAUDE_CODE_DEBUG_LOG_LEVEL=info

# Debug logs directory
# CLAUDE_CODE_DEBUG_LOGS_DIR=

# Enable startup profiling
# CLAUDE_CODE_PROFILE_STARTUP=true

# General debug flag
# DEBUG=true

# ── Privacy & Telemetry ─────────────────────────────────────────────────────
# Disable telemetry
# DISABLE_TELEMETRY=true

# Disable non-essential network traffic
# CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=true

# ── Proxy & Network ─────────────────────────────────────────────────────────
# HTTPS proxy
# HTTPS_PROXY=

# Custom SSL certificate
# SSL_CERT_FILE=

# =============================================================================
# ─── OAUTH STUB NOTES (Part D) ─────────────────────────────────────────────
# =============================================================================
#
# The OAuth flow (src/services/oauth/) requires a browser and Anthropic's
# OAuth endpoints. For development, you do NOT need to stub anything —
# just set ANTHROPIC_API_KEY and the auth system will skip OAuth automatically.
#
# How it works:
#   src/utils/auth.ts — isAnthropicAuthEnabled() checks whether OAuth should
#   be attempted. When it detects ANTHROPIC_API_KEY in the environment (and
#   the context is not a "managed OAuth" context like Claude Desktop), it
#   returns false, which causes the entire OAuth path to be bypassed.
#
# Decision chain:
#   1. isAnthropicAuthEnabled() in src/utils/auth.ts (line ~111)
#      → returns false if external API key is detected
#   2. isClaudeAISubscriber() in src/utils/auth.ts (line ~1715)
#      → checks OAuth tokens for user:inference scope (never reached if #1 is false)
#   3. getAnthropicApiKey() in src/utils/auth.ts (line ~201)
#      → resolves API key from env/keychain/config
#
# If you needed to FORCE bypass OAuth in all cases (e.g. for testing the
# OAuth code paths themselves), you could:
#   - Use --bare flag (sets CLAUDE_CODE_SIMPLE=1, disables OAuth in isBareMode())
#   - Set CLAUDE_CODE_USE_BEDROCK=true + CLAUDE_CODE_SKIP_BEDROCK_AUTH=true
#     (routes around OAuth entirely but creates a Bedrock-shaped client)
#   - Directly modify isAnthropicAuthEnabled() to return false (not recommended
#     for production)
#
# Bottom line: export ANTHROPIC_API_KEY="sk-ant-..." is sufficient for dev.
# =============================================================================