# Appendix B: Environment Variable Reference

This appendix lists the key user-configurable environment variables in Claude Code v2.1.88. Grouped by functional domain, only variables affecting user-visible behavior are listed; internal telemetry and platform detection variables are omitted.

## Context Compaction

| Variable | Effect | Default |
|----------|--------|---------|
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Override context window size (tokens) | Model default |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Override auto-compaction threshold as percentage (0-100) | Computed value |
| `DISABLE_AUTO_COMPACT` | Completely disable auto-compaction | `false` |

## Effort and Reasoning

| Variable | Effect | Valid Values |
|----------|--------|-------------|
| `CLAUDE_CODE_EFFORT_LEVEL` | Override effort level | `low`, `medium`, `high`, `max`, `auto`, `unset` |
| `CLAUDE_CODE_DISABLE_FAST_MODE` | Disable Fast Mode accelerated output | `true`/`false` |
| `DISABLE_INTERLEAVED_THINKING` | Disable extended thinking | `true`/`false` |
| `MAX_THINKING_TOKENS` | Override thinking token limit | Model default |

## Tools and Output Limits

| Variable | Effect | Default |
|----------|--------|---------|
| `BASH_MAX_OUTPUT_LENGTH` | Max output characters for Bash commands | 8,000 |
| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Glob search timeout (seconds) | Default |

## Permissions and Security

| Variable | Effect | Note |
|----------|--------|------|
| `CLAUDE_CODE_DUMP_AUTO_MODE` | Export YOLO classifier requests/responses | Debug only |
| `CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK` | Disable Bash command injection detection | Reduces security |

## API and Authentication

| Variable | Effect | Security Level |
|----------|--------|---------------|
| `ANTHROPIC_API_KEY` | Anthropic API authentication key | Credential |
| `ANTHROPIC_BASE_URL` | Custom API endpoint (proxy support) | Redirectable |
| `ANTHROPIC_MODEL` | Override default model | Safe |
| `CLAUDE_CODE_USE_BEDROCK` | Route inference through AWS Bedrock | Safe |
| `CLAUDE_CODE_USE_VERTEX` | Route inference through Google Vertex AI | Safe |
| `CLAUDE_CODE_EXTRA_BODY` | Append extra fields to API requests | Advanced use |
| `ANTHROPIC_CUSTOM_HEADERS` | Custom HTTP request headers | Safe |

## Model Selection

| Variable | Effect | Example |
|----------|--------|---------|
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Custom Haiku model ID | Model string |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Custom Sonnet model ID | Model string |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Custom Opus model ID | Model string |
| `ANTHROPIC_SMALL_FAST_MODEL` | Fast inference model (e.g., for summaries) | Model string |
| `CLAUDE_CODE_SUBAGENT_MODEL` | Model used by sub-Agents | Model string |

## Prompt Caching

| Variable | Effect | Default |
|----------|--------|---------|
| `CLAUDE_CODE_ENABLE_PROMPT_CACHING` | Enable prompt caching | `true` |
| `DISABLE_PROMPT_CACHING` | Completely disable prompt caching | `false` |

## Session and Debugging

| Variable | Effect | Purpose |
|----------|--------|---------|
| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Log verbosity | `silent`/`error`/`warn`/`info`/`verbose` |
| `CLAUDE_CODE_PROFILE_STARTUP` | Enable startup performance profiling | Debug |
| `CLAUDE_CODE_PROFILE_QUERY` | Enable query pipeline profiling | Debug |
| `CLAUDE_CODE_JSONL_TRANSCRIPT` | Write session transcript as JSONL | File path |
| `CLAUDE_CODE_TMPDIR` | Override temporary directory | Path |

## Output and Formatting

| Variable | Effect | Default |
|----------|--------|---------|
| `CLAUDE_CODE_SIMPLE` | Minimal system prompt mode | `false` |
| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Disable setting terminal title | `false` |
| `CLAUDE_CODE_NO_FLICKER` | Reduce fullscreen mode flickering | `false` |

## MCP (Model Context Protocol)

| Variable | Effect | Default |
|----------|--------|---------|
| `MCP_TIMEOUT` | MCP server connection timeout (ms) | 10,000 |
| `MCP_TOOL_TIMEOUT` | MCP tool call timeout (ms) | 30,000 |
| `MAX_MCP_OUTPUT_TOKENS` | MCP tool output token limit | Default |

## Network and Proxy

| Variable | Effect | Note |
|----------|--------|------|
| `HTTP_PROXY` / `HTTPS_PROXY` | HTTP/HTTPS proxy | Redirectable |
| `NO_PROXY` | Host list to bypass proxy | Safe |
| `NODE_EXTRA_CA_CERTS` | Additional CA certificates | Affects TLS trust |

## Paths and Configuration

| Variable | Effect | Default |
|----------|--------|---------|
| `CLAUDE_CONFIG_DIR` | Override Claude configuration directory | `~/.claude` |

---

## Version Evolution: v2.1.91 New Variables

| Variable | Effect | Notes |
|----------|--------|-------|
| `CLAUDE_CODE_AGENT_COST_STEER` | Sub-agent cost steering | Controls resource consumption in multi-agent scenarios |
| `CLAUDE_CODE_RESUME_THRESHOLD_MINUTES` | Session resume time threshold | Controls the time window for session resumption |
| `CLAUDE_CODE_RESUME_TOKEN_THRESHOLD` | Session resume token threshold | Controls the token budget for session resumption |
| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | AWS authentication path | Enables Anthropic AWS infrastructure authentication |
| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Skip AWS authentication | Fallback path when AWS is unavailable |
| `CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL` | Disable Claude API skill | Enterprise compliance scenario control |
| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Plugin marketplace fault tolerance | Retain cached version when marketplace fetch fails |
| `CLAUDE_CODE_REMOTE_SETTINGS_PATH` | Remote settings path override | Custom settings URL for enterprise deployment |

### v2.1.91 Removed Variables

| Variable | Original Effect | Removal Reason |
|----------|----------------|----------------|
| `CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK` | Disable command injection check | Tree-sitter infrastructure entirely removed |
| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | Disable mouse clicks | Feature deprecated |
| `CLAUDE_CODE_MCP_INSTR_DELTA` | MCP instruction delta | Feature refactored |

---

## Configuration Priority System

Environment variables are just one facet of Claude Code's configuration system. The complete configuration system is composed of 6 layers of sources, merged from lowest to highest priority — later sources override earlier ones. Understanding this priority chain is crucial for diagnosing "why isn't my setting taking effect."

### Six-Layer Priority Model

Configuration sources are defined in `restored-src/src/utils/settings/constants.ts:7-22`, and the merge logic is implemented in the `loadSettingsFromDisk()` function at `restored-src/src/utils/settings/settings.ts:644-796`:

| Priority | Source ID | File Path / Source | Description |
|----------|-----------|-------------------|-------------|
| 0 (lowest) | pluginSettings | Plugin-provided base settings | Only includes whitelisted fields (e.g., `agent`), serves as the base layer for all file sources |
| 1 | `userSettings` | `~/.claude/settings.json` | User global settings, applies across all projects |
| 2 | `projectSettings` | `$PROJECT/.claude/settings.json` | Project shared settings, committed to version control |
| 3 | `localSettings` | `$PROJECT/.claude/settings.local.json` | Project local settings, automatically added to `.gitignore` |
| 4 | `flagSettings` | `--settings` CLI parameter + SDK inline settings | Temporary overrides passed via command line or SDK |
| 5 (highest) | `policySettings` | Enterprise managed policies (multiple competing sources) | Enterprise admin enforced policies, see below |

### Merge Semantics

Merging uses lodash's `mergeWith` for deep merge, with a custom merger defined at `restored-src/src/utils/settings/settings.ts:538-547`:

- **Objects**: Recursively merged, later source fields override earlier ones
- **Arrays**: Merged and deduplicated (`mergeArrays`), not replaced — this means `permissions.allow` rules from multiple layers accumulate
- **`undefined` values**: Interpreted as "delete this key" in `updateSettingsForSource` (`restored-src/src/utils/settings/settings.ts:482-486`)

This array merge semantic is particularly important: if a user allows a tool in `userSettings` and allows another tool in `projectSettings`, the final `permissions.allow` list includes both. This enables multi-layer permission configurations to stack rather than override each other.

### Policy Settings (policySettings) Four-Layer Competition

Policy settings (`policySettings`) have their own internal priority chain, using a "first source with content wins" strategy, implemented at `restored-src/src/utils/settings/settings.ts:322-345`:

| Sub-priority | Source | Description |
|-------------|--------|-------------|
| 1 (highest) | Remote Managed Settings | Enterprise policy cache synced from API |
| 2 | MDM Native Policies (HKLM / macOS plist) | System-level policies read via `plutil` or `reg query` |
| 3 | File Policies (`managed-settings.json` + `managed-settings.d/*.json`) | Drop-in directory support, merged in alphabetical order |
| 4 (lowest) | HKCU User Policies (Windows only) | User-level registry settings |

Note that policy settings merge differently from other sources: the four sub-sources within policies are in a **competitive relationship** (first one wins), while policies as a whole are in an **additive relationship** with other sources (deep merged to the top of the configuration chain).

### Override Chain Flowchart

```mermaid
flowchart TD
    P["pluginSettings<br/>Plugin base settings"] -->|mergeWith| U["userSettings<br/>~/.claude/settings.json"]
    U -->|mergeWith| Proj["projectSettings<br/>.claude/settings.json"]
    Proj -->|mergeWith| L["localSettings<br/>.claude/settings.local.json"]
    L -->|mergeWith| F["flagSettings<br/>--settings CLI / SDK inline"]
    F -->|mergeWith| Pol["policySettings<br/>Enterprise managed policies"]
    Pol --> Final["Final effective config<br/>getInitialSettings()"]

    subgraph PolicyInternal["policySettings internal competition (first wins)"]
        direction TB
        R["Remote Managed<br/>Remote API"] -.->|empty?| MDM["MDM Native<br/>plist / HKLM"]
        MDM -.->|empty?| MF["File Policies<br/>managed-settings.json"]
        MF -.->|empty?| HK["HKCU<br/>Windows user-level"]
    end

    Pol --- PolicyInternal

    style Final fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    style PolicyInternal fill:#fff3e0,stroke:#FF9800
```

**Figure B-1: Configuration Priority Override Chain**

### Caching and Invalidation

Configuration loading has a two-layer caching mechanism (`restored-src/src/utils/settings/settingsCache.ts`):

1. **File-level cache**: `parseSettingsFile()` caches the parsed result of each file, avoiding repeated JSON parsing
2. **Session-level cache**: `getSettingsWithErrors()` caches the merged final result, reused throughout the session

Caches are uniformly invalidated via `resetSettingsCache()` — triggered when the user modifies settings through the `/config` command or `updateSettingsForSource()`. Settings file change detection is handled by `restored-src/src/utils/settings/changeDetector.ts`, which drives React component re-rendering through file system watching.

### Diagnostic Recommendations

When a setting "isn't taking effect," troubleshoot in this order:

1. **Confirm the source**: Use the `/config` command to view the current effective configuration and source annotations
2. **Check priority**: Is a higher-priority source overriding your setting? `policySettings` is the strongest override
3. **Check array merging**: Permission rules are additive — if a `deny` rule appears in a higher-priority source, a lower-priority `allow` cannot override it
4. **Check caching**: After modifying `.json` files within the same session, the configuration may still be cached — restart the session or use `/config` to trigger a refresh