The Unofficial Guide to Every Claude Code Environment Flag

Claude Code has over 150 undocumented environment variables hiding in the binary. We extracted them all, traced their usage, and grouped them so you can tune your setup for cost, speed, or capability.

14 April 202633 min read
AI-Ometer— slop disclosure index
Mostly AI85%
 

The Unofficial Guide to Every Claude Code Environment Flag

Claude Code exposes over 150 environment variables that control everything from model selection and token budgets to sandbox behaviour and telemetry. Most are undocumented. We extracted the full list from the binary using strings and traced each one back to its usage in the minified source. This post catalogues every flag we found, grouped by domain, so you can tune Claude Code to fit your workflow.

Version notice: This reference was generated on 14 April 2026 from Claude Code v2.1.83. Environment flags are internal and subject to change — flags may be added, removed, or renamed in any release. If you're running a different version, verify against your own binary with strings $(which claude) | grep -oE 'CLAUDE_CODE_[A-Z_]+'. Treat this as a point-in-time snapshot, not a stable API contract.

Set any of these via env in your settings.json or export them in your shell before launching Claude Code.

Table of Contents

Authentication and Identity

These flags control how Claude Code authenticates with the API and identifies your account. None of them directly affect token usage.

Account Tagged Id

CLAUDE_CODE_ACCOUNT_TAGGED_ID — Sets the account tagged ID used for internal tagging and telemetry. Part of the OAuth account structure used for user identification.

Account Uuid

CLAUDE_CODE_ACCOUNT_UUID — Sets the account UUID for authentication. Used in the oauthAccount.accountUuid structure for identifying your account.

Api Base Url

CLAUDE_CODE_API_BASE_URL — Overrides the default Anthropic API base URL. Useful for custom deployments, enterprise proxies, or testing environments. Routing to a different endpoint could affect billing, but the flag itself does not change token consumption.

Api Key File Descriptor

CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR — Reads the API key from an integer file descriptor instead of directly from the environment or config file. Designed for secure credential passing to subprocesses without exposing keys in the process environment.

Api Key Helper Ttl Ms

CLAUDE_CODE_API_KEY_HELPER_TTL_MS — Sets the time-to-live in milliseconds for the API key helper cache. Determines how long cached credentials from an API key helper script remain valid before being refreshed.

Attribution Header

CLAUDE_CODE_ATTRIBUTION_HEADER — Controls whether attribution headers are sent with API requests. When enabled (the default), sends version and entrypoint info in an x-anthropic-billing-header like cc_version=2.1.83; cc_entrypoint=<value>.

Custom Oauth Url

CLAUDE_CODE_CUSTOM_OAUTH_URL — Overrides the default OAuth endpoint URL. Must be an approved endpoint — the system will error if the URL is not on the approved list. Used for custom or enterprise OAuth providers.

Oauth Client Id

CLAUDE_CODE_OAUTH_CLIENT_ID — Sets the OAuth client ID used during the authentication handshake.

Oauth Refresh Token

CLAUDE_CODE_OAUTH_REFRESH_TOKEN — Provides an OAuth refresh token for obtaining new access tokens when the current one expires.

Oauth Scopes

CLAUDE_CODE_OAUTH_SCOPES — Sets the OAuth scopes requested during authentication, defining what permissions the token carries. Required when using CLAUDE_CODE_OAUTH_REFRESH_TOKEN. Values are space-separated, e.g. user:profile user:inference user:sessions:claude_code user:mcp_servers.

Oauth Token

CLAUDE_CODE_OAUTH_TOKEN — Sets the OAuth access token directly, used as the bearer token for API authentication.

Oauth Token File Descriptor

CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR — Reads the OAuth token from a file descriptor. Same secure-passing pattern as API_KEY_FILE_DESCRIPTOR but for OAuth tokens.

Organization Uuid

CLAUDE_CODE_ORGANIZATION_UUID — Sets the organization UUID for multi-org accounts. Sent in the X-Organization-Uuid header when the session token starts with sk-ant-sid. Used for organization-level billing and permissions routing.

Session Access Token

CLAUDE_CODE_SESSION_ACCESS_TOKEN — Sets a session-specific access token. Handles sk-ant-sid tokens specially (uses a Cookie header with sessionKey), otherwise uses standard Bearer auth. Can also read from CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR.

User Email

CLAUDE_CODE_USER_EMAIL — Sets the user email for identification, attribution, and analytics logging.

Websocket Auth File Descriptor

CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR — Reads WebSocket authentication credentials from a file descriptor. Used for real-time communication features like IDE connections and MCP servers.

Api Key (Anthropic)

ANTHROPIC_API_KEY — The standard Anthropic API key for direct API access. Either this or CLAUDE_CODE_OAUTH_TOKEN is required for authentication.

Auth Token (Anthropic)

ANTHROPIC_AUTH_TOKEN — An alternative authentication token format used in some authentication flows.

Base Url (Anthropic)

ANTHROPIC_BASE_URL — Overrides the Anthropic API base URL (default: https://api.anthropic.com). Used for proxies or custom deployments.

Unix Socket (Anthropic)

ANTHROPIC_UNIX_SOCKET — Unix socket path for local API connections. Useful for local testing or custom setups where TCP is not desired.

Context and Memory

These flags control what gets loaded into the conversation context — CLAUDE.md files, auto-memory, git instructions, compaction behaviour, and prompt history. Many of these are among the highest-impact levers for token usage.

Additional Directories Claude Md

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD — Adds extra directories to scan for CLAUDE.md files beyond the standard locations (Managed, User, Project, Local). When set, the system iterates through each directory and loads CLAUDE.md, .claude/CLAUDE.md, and .claude/rules from each.

Affects token usage. More directories means more CLAUDE.md content loaded into the system prompt.

Auto Compact Window

CLAUDE_CODE_AUTO_COMPACT_WINDOW — Overrides the effective context window size used for auto-compaction calculations. When set to a positive integer, limits the compaction window to the minimum of the configured window and the parsed value. A smaller value triggers compaction earlier.

Affects token usage. Lower values mean more aggressive compaction, reducing how many tokens are carried forward in context.

Disable Auto Memory

CLAUDE_CODE_DISABLE_AUTO_MEMORY — Disables the auto-memory system when set to a truthy value (e.g. "1"). Claude will not automatically read from or write to the project's memory/ directory. Your manual memory DB and CLAUDE.md files remain unaffected.

Affects token usage. Removes auto-memory content from the context window.

Disable Claude Mds

CLAUDE_CODE_DISABLE_CLAUDE_MDS — Completely disables loading of all CLAUDE.md files. Sets a claudemd_disabled flag and returns null instead of loading content. This is the nuclear option for system prompt reduction.

Affects token usage. Can massively reduce system prompt size depending on how many and how large your CLAUDE.md files are.

Disable Git Instructions

CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS — Strips built-in git and PR workflow instructions from the system prompt. When truthy, excludes git status, branch info, recent commits, and the git workflow guide. Falls back to the includeGitInstructions setting when not set.

Affects token usage. Removes a significant chunk of system prompt tokens related to git workflows.

Disable Precompact Skip

CLAUDE_CODE_DISABLE_PRECOMPACT_SKIP — Disables the optimization that skips pre-compaction in certain cases. When set, compaction always runs the full pipeline rather than short-circuiting.

Affects token usage. May change compaction behaviour, affecting how much context is retained.

Include Partial Messages

CLAUDE_CODE_INCLUDE_PARTIAL_MESSAGES — Controls whether partial messages are included in the conversation. In SDK mode, automatically sets certain stream formats to stream-json when enabled.

Affects token usage. May increase context size by including incomplete message fragments.

Mcp Instr Delta

CLAUDE_CODE_MCP_INSTR_DELTA — Enables delta-based MCP instruction updates. Instead of sending full instruction sets each time MCP server instructions change, sends only the additions and removals. Tracks added/removed server names using mcp_instructions_delta attachments. Falls back to the tengu_basalt_3kr experiment flag when not set.

Affects token usage. Optimizes token usage by avoiding redundant instruction text when MCP servers change.

Remote Memory Dir

CLAUDE_CODE_REMOTE_MEMORY_DIR — Specifies an alternative directory for storing memory and session data in remote mode. Affects storage location only.

Resume Interrupted Turn

CLAUDE_CODE_RESUME_INTERRUPTED_TURN — Enables auto-resuming of interrupted turns. When set and the interrupted turn is not none, automatically re-queues the interrupted message for processing.

Save Hook Additional Context

CLAUDE_CODE_SAVE_HOOK_ADDITIONAL_CONTEXT — Persists additional context generated by hooks. When enabled, hook output tagged as additionalContext is injected back into the conversation.

Affects token usage. Extra context from hooks adds to the conversation window.

Skip Prompt History

CLAUDE_CODE_SKIP_PROMPT_HISTORY — Skips loading prompt history at session start. Reduces the initial context load.

Affects token usage. Less history loaded means fewer tokens consumed at the start of a session.

Sm Compact

CLAUDE_CODE_SM_COMPACT — Controls Session Memory compaction. When enabled, automatically compacts conversation history using session memory summaries with configurable thresholds (minTokens: 10k, minTextBlockMessages: 5, maxTokens: 40k). Can also be toggled via ENABLE_CLAUDE_CODE_SM_COMPACT / DISABLE_CLAUDE_CODE_SM_COMPACT variants, or falls back to the tengu_session_memory and tengu_sm_compact experiment flags.

Affects token usage. Major impact — automatically summarises and compresses conversation history, significantly reducing token consumption while maintaining context continuity.

Debugging and Diagnostics

Instrumentation and profiling flags. None of these affect token usage — they observe existing behaviour without changing it.

Debug Log Level

CLAUDE_CODE_DEBUG_LOG_LEVEL — Sets the minimum log level for debug output. Valid values: verbose (0), debug (1), info (2), warn (3), error (4). Defaults to debug if not set or invalid.

Debug Logs Dir

CLAUDE_CODE_DEBUG_LOGS_DIR — Specifies the directory for debug log files. Falls back to ~/.claude/debug/<session-id>.txt. A latest symlink points to the current session's log file.

Debug Repaints

CLAUDE_CODE_DEBUG_REPAINTS — Intended to debug UI repaint cycles. Not found in the v2.1.83 binary — may be unused or removed.

Diagnostics File

CLAUDE_CODE_DIAGNOSTICS_FILE — Specifies a file path for writing diagnostic information including operation timings and results.

Frame Timing Log

CLAUDE_CODE_FRAME_TIMING_LOG — Intended for logging UI frame timing. Not found in the v2.1.83 binary — may be unused or removed.

Perfetto Trace

CLAUDE_CODE_PERFETTO_TRACE — Enables Perfetto performance tracing. Initializes trace collection with metadata (process names, thread names, parent agent IDs) and instruments API calls, tool executions, and timing spans.

Profile Query

CLAUDE_CODE_PROFILE_QUERY — Intended for query profiling. Not clearly implemented in the v2.1.83 binary.

Profile Startup

CLAUDE_CODE_PROFILE_STARTUP — When set to "1", enables detailed startup profiling. Records performance marks at checkpoints (cli_entry, imports_loaded, init_start, settings_load, etc.) and writes a report to ~/.claude/startup-perf/<session-id>.txt with timing deltas and memory usage (RSS, heap). Also enables 0.5% statistical sampling for telemetry.

Slow Operation Threshold Ms

CLAUDE_CODE_SLOW_OPERATION_THRESHOLD_MS — Intended to set a threshold for slow operation warnings. Not clearly implemented in the v2.1.83 binary.

Stall Timeout Ms For Testing

CLAUDE_CODE_STALL_TIMEOUT_MS_FOR_TESTING — A testing-only flag for stall detection timeout. Likely not compiled into production builds.

IDE and Editor Integration

Flags for connecting Claude Code to VS Code, Cursor, Windsurf, and JetBrains. None affect token usage.

Auto Connect Ide

CLAUDE_CODE_AUTO_CONNECT_IDE — When truthy, Claude Code automatically attempts to connect to supported IDEs and install the Claude Code extension if not already present. Checks multiple conditions including SSE port presence and validates workspace folders before establishing the connection.

Ide Host Override

CLAUDE_CODE_IDE_HOST_OVERRIDE — Overrides the default host address for IDE connections (defaults to 127.0.0.1, or auto-detected Windows host IP in WSL environments). Bypasses automatic host detection logic when set. Useful for WSL or custom network configurations.

Ide Skip Auto Install

CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL — When truthy, skips automatic installation of the Claude Code IDE extension for VS Code-based editors and JetBrains IDEs. The auto-installation branch is skipped entirely.

Ide Skip Valid Check

CLAUDE_CODE_IDE_SKIP_VALID_CHECK — Bypasses workspace folder validation when connecting to IDEs. Normally, Claude Code confirms the current working directory matches one of the IDE's workspace folders. This flag marks the connection as valid regardless, useful for testing or non-standard setups.

Model and Effort

These flags control which models are used, how hard they think, and how much output they produce. Most of them directly affect token usage and cost.

Always Enable Effort

CLAUDE_CODE_ALWAYS_ENABLE_EFFORT — Forces the effort feature to be enabled regardless of model. By default, effort levels are only available for Opus 4.6, Sonnet 4.6, and first-party deployments. This flag bypasses that check.

Affects token usage. Enables effort-level control on models that wouldn't normally support it, which determines how much reasoning the model performs.

Disable Adaptive Thinking

CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING — Disables adaptive thinking mode. The system falls back to fixed thinking budgets based on effort level instead of dynamically adjusting. Only affects models that support thinking (Sonnet 4 and Opus 4 series).

Affects token usage. Adaptive thinking dynamically scales the token budget per task. Disabling it uses a fixed budget which may be higher or lower depending on the task.

Disable Fast Mode

CLAUDE_CODE_DISABLE_FAST_MODE — Prevents fast mode from being enabled even when available. When not disabled, fast mode can be toggled on to add a beta header and set speed: "fast" in API requests for supported models.

Affects token usage. Fast mode optimises response generation, potentially changing token consumption patterns.

Disable Legacy Model Remap

CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP — Prevents automatic remapping of legacy model names to current models. Without this flag, older model IDs may be transparently upgraded to newer versions.

Disable Nonstreaming Fallback

CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK — Disables the automatic fallback to non-streaming mode when streaming fails. The system will no longer retry failed streaming requests as non-streaming.

Disable Thinking

CLAUDE_CODE_DISABLE_THINKING — Completely disables extended thinking even on models that support it. This is more aggressive than disabling adaptive thinking — no thinking tokens are used at all.

Affects token usage. Eliminates all thinking tokens, which can represent a significant portion of total token consumption.

Effort Level

CLAUDE_CODE_EFFORT_LEVEL — Overrides the effort level for the session. Valid values: low, medium, high, or max. Set to unset or auto to let the system choose automatically (these return null internally). Takes precedence over user settings. The max level is only available on Opus 4.6.

Affects token usage. Directly controls the thinking budget — higher effort means more reasoning tokens.

Max Output Tokens

CLAUDE_CODE_MAX_OUTPUT_TOKENS — Overrides the maximum output tokens for API requests. Directly sets the max_tokens parameter, limiting how many tokens the model can generate per response.

Affects token usage. Hard cap on output tokens per response.

Subagent Model

CLAUDE_CODE_SUBAGENT_MODEL — Forces a specific model for all subagents. Overrides subagent model selection logic entirely. Common values: sonnet, haiku, or a full model ID.

Affects token usage. Cheaper subagent models reduce cost per delegated task at the expense of capability.

Betas (Anthropic)

ANTHROPIC_BETAS — Enables beta API features by adding beta headers to API requests. Beta features may include new capabilities that affect token consumption, such as extended thinking or prompt caching.

Custom Headers (Anthropic)

ANTHROPIC_CUSTOM_HEADERS — Allows adding custom HTTP headers to all Anthropic API requests.

Custom Model Option (Anthropic)

ANTHROPIC_CUSTOM_MODEL_OPTION — Allows defining a custom model option in the CLI model picker. Used alongside ANTHROPIC_CUSTOM_MODEL_OPTION_NAME and ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION for adding non-standard models to the selection interface.

Default Haiku Model (Anthropic)

ANTHROPIC_DEFAULT_HAIKU_MODEL — Overrides which specific model ID maps to the "haiku" tier. Affects cost and capability of all haiku-tier tasks.

Affects token usage. Different model versions may have different context windows and pricing.

Default Opus Model (Anthropic)

ANTHROPIC_DEFAULT_OPUS_MODEL — Overrides which specific model ID maps to the "opus" tier.

Affects token usage. Controls cost and capability of opus-tier tasks.

Default Sonnet Model (Anthropic)

ANTHROPIC_DEFAULT_SONNET_MODEL — Overrides which specific model ID maps to the "sonnet" tier.

Affects token usage. Controls cost and capability of sonnet-tier tasks.

Log (Anthropic)

ANTHROPIC_LOG — Controls logging level for the Anthropic SDK. Default is warn. Valid values follow standard log levels.

Model (Anthropic)

ANTHROPIC_MODEL — Sets the primary model for API requests. Standard Anthropic SDK environment variable.

Affects token usage. Different models have different capabilities, context windows, and token pricing.

Small Fast Model (Anthropic)

ANTHROPIC_SMALL_FAST_MODEL — Specifies an alternative smaller, faster model for lightweight internal tasks such as hook evaluation, classification, and other utility operations that don't require the full capabilities of the primary model.

Affects token usage. Routes lightweight operations to a cheaper model, reducing overall token costs.

Small Fast Model Aws Region (Anthropic)

ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION — Sets the AWS region for the small/fast model when using Bedrock deployment. Configuration only.

MCP, Plugins, and Features

Flags for managing MCP servers, plugins, feature flags, and tool behaviour.

Disable Advisor Tool

CLAUDE_CODE_DISABLE_ADVISOR_TOOL — Removes the Advisor tool from the available tool set. The advisor tool schema and interactions are excluded entirely.

Affects token usage. One fewer tool definition in the system prompt, plus no advisor-related interactions.

Disable Attachments

CLAUDE_CODE_DISABLE_ATTACHMENTS — Disables all attachment generation including file references and diagnostics.

Affects token usage. Significantly reduces tokens by removing attachments from the conversation.

Disable Background Tasks

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS — Prevents background task processing. Background tasks may generate additional context or API calls.

Affects token usage. Background tasks can consume tokens; disabling them prevents that.

Disable Cron

CLAUDE_CODE_DISABLE_CRON — Disables cron/scheduled task support.

Disable Experimental Betas

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — Disables all experimental beta features. Some beta features may carry token overhead.

Disable Feedback Survey

CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY — Disables feedback survey prompts in the UI.

Disable File Checkpointing

CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING — Disables file state checkpointing/snapshots.

Disable Official Marketplace Autoinstall

CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL — Prevents automatic installation of official marketplace plugins on startup.

Enable Cfc

CLAUDE_CODE_ENABLE_CFC — Enables the CFC feature (likely related to caching or function calling). May affect caching behaviour.

Enable Fine Grained Tool Streaming

CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING — Enables streaming tool results at finer granularity. Affects delivery mechanism, not content.

Enable Prompt Suggestion

CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION — Enables AI-generated prompt suggestions in the UI.

Affects token usage. Suggestions require lightweight model calls to generate.

Enable Sdk File Checkpointing

CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING — Enables file checkpointing specifically in SDK mode.

Enable Token Usage Attachment

CLAUDE_CODE_ENABLE_TOKEN_USAGE_ATTACHMENT — Adds token usage statistics as attachments in the conversation.

Affects token usage. Adds a small attachment with token stats to each turn.

Enable Xaa

CLAUDE_CODE_ENABLE_XAA — Enables the XAA feature (Extended Agent Actions or similar). Experimental.

Extra Body

CLAUDE_CODE_EXTRA_BODY — Adds extra fields to the API request body. Impact depends on what fields are added — could include token-related parameters.

Extra Metadata

CLAUDE_CODE_EXTRA_METADATA — Adds extra metadata to API requests. Metadata only, no content impact.

Force Global Cache

CLAUDE_CODE_FORCE_GLOBAL_CACHE — Forces use of the global prompt cache. May reduce costs by improving cache hit rates.

Max Tool Use Concurrency

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY — Sets the maximum number of tools to execute concurrently. Controls execution parallelism, not the amount of content generated.

Plugin Cache Dir

CLAUDE_CODE_PLUGIN_CACHE_DIR — Sets the directory for plugin cache storage.

Plugin Git Timeout Ms

CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS — Timeout in milliseconds for Git operations when installing plugins.

Plugin Seed Dir

CLAUDE_CODE_PLUGIN_SEED_DIR — Directory containing seed/bundled plugins.

Plugin Use Zip Cache

CLAUDE_CODE_PLUGIN_USE_ZIP_CACHE — Uses ZIP-based cache for plugin storage instead of the default.

Post For Session Ingress V

CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V — Version selector for the session ingress POST endpoint. API versioning only.

Subprocess Env Scrub

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB — Scrubs/sanitises environment variables when spawning subprocesses. A security feature.

Sync Plugin Install

CLAUDE_CODE_SYNC_PLUGIN_INSTALL — Makes plugin installation synchronous instead of async.

Sync Plugin Install Timeout Ms

CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS — Timeout in milliseconds for synchronous plugin installation.

Networking and Proxy

Flags for configuring network connections, proxies, and TLS. None directly affect token usage.

Client Cert

CLAUDE_CODE_CLIENT_CERT — Specifies a client certificate file path for TLS/mTLS authentication when connecting to proxy servers or APIs.

Client Key

CLAUDE_CODE_CLIENT_KEY — Specifies the private key file path corresponding to the client certificate for TLS authentication.

Client Key Passphrase

CLAUDE_CODE_CLIENT_KEY_PASSPHRASE — Provides the passphrase to decrypt an encrypted client key file.

Host Http Proxy Port

CLAUDE_CODE_HOST_HTTP_PROXY_PORT — Port number for an HTTP proxy server running on the host machine. Used in sandboxed or containerised environments.

Host Socks Proxy Port

CLAUDE_CODE_HOST_SOCKS_PROXY_PORT — Port number for a SOCKS5 proxy server running on the host machine.

Proxy Resolves Hosts

CLAUDE_CODE_PROXY_RESOLVES_HOSTS — When enabled, DNS resolution happens through the proxy server instead of locally.

Skip Bedrock Auth

CLAUDE_CODE_SKIP_BEDROCK_AUTH — Skips the AWS Bedrock credential authentication flow.

Skip Fast Mode Network Errors

CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS — In fast mode, network errors that would normally pause or retry are skipped to maintain speed. May indirectly affect token usage if errors cause re-sends.

Skip Foundry Auth

CLAUDE_CODE_SKIP_FOUNDRY_AUTH — Skips the Anthropic Foundry authentication flow.

Skip Vertex Auth

CLAUDE_CODE_SKIP_VERTEX_AUTH — Skips the Google Vertex AI authentication flow.

Output and Display

Flags controlling how Claude Code renders output in the terminal. A few of these can indirectly reduce token usage by encouraging terser responses.

Accessibility

CLAUDE_CODE_ACCESSIBILITY — Enables accessibility features for screen readers and assistive technology. Affects how content is rendered in the terminal UI.

Brief

CLAUDE_CODE_BRIEF — Enables brief/condensed output mode. Checked in multiple rendering contexts throughout the codebase, reducing decorative elements and focusing on core content.

Affects token usage. By encouraging shorter output, may indirectly reduce output tokens.

Brief Upload

CLAUDE_CODE_BRIEF_UPLOAD — Controls whether to use brief attachment upload mode. Can be set independently or is automatically enabled when replBridgeEnabled is active. Uses an alternate, more compact upload path for file attachments.

Affects token usage. May reduce overhead in how attachment data is transmitted.

Disable Terminal Title

CLAUDE_CODE_DISABLE_TERMINAL_TITLE — Prevents Claude Code from setting the terminal window title via escape sequences.

Disable Virtual Scroll

CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL — Disables virtual scrolling in the terminal UI. Virtual scrolling renders only visible content as a performance optimisation. Disabling it renders all content immediately.

Eager Flush

CLAUDE_CODE_EAGER_FLUSH — Forces immediate flushing of output buffers after each operation. Also triggered automatically in cowork mode. Useful for debugging or ensuring real-time output.

Exit After First Render

CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER — Causes Claude Code to exit immediately after the first UI render. A testing flag — skips various initialisation and prefetch operations. Used for measuring startup time.

Exit After Stop Delay

CLAUDE_CODE_EXIT_AFTER_STOP_DELAY — When set to a number (milliseconds), Claude Code automatically exits after that many milliseconds of idle time following a stop condition. Used for headless and automation scenarios.

Force Full Logo

CLAUDE_CODE_FORCE_FULL_LOGO — Forces display of the full ASCII Claude logo, even if the terminal width would suggest a compact version.

Question Preview Format

CLAUDE_CODE_QUESTION_PREVIEW_FORMAT — Controls the format for displaying question/prompt previews in the UI.

Simple

CLAUDE_CODE_SIMPLE — Enables simplified output mode with minimal UI decorations. Checked in numerous rendering contexts. Strips colours, formatting, and decorative elements.

Affects token usage. By reducing output complexity, may indirectly affect response token usage.

Syntax Highlight

CLAUDE_CODE_SYNTAX_HIGHLIGHT — Controls whether syntax highlighting is enabled for code blocks. Uses the bat library under the hood.

Syntax Highlight Bat Theme

CLAUDE_CODE_SYNTAX_HIGHLIGHTBAT_THEMEF — Specifies the bat theme for syntax highlighting. The env var name contains a typo (THEMEF instead of THEME) in the actual implementation — this is the real name you need to use.

Planning and Tasks

Flags for plan mode, task management, and multi-agent coordination. Several affect token usage by adding planning context or enabling additional agent activity.

Agent Name

CLAUDE_CODE_AGENT_NAME — Sets the name/identifier for an agent instance. Metadata only.

Agent Rule Disabled

CLAUDE_CODE_AGENT_RULE_DISABLED — Disables agent-specific rules or constraints. May reduce rule-related system prompt content.

Blocking Limit Override

CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE — Overrides the default blocking limit for context window usage. Sets a custom threshold before the session blocks due to token exhaustion.

Affects token usage. Controls when compaction or blocking occurs based on token count.

Enable Tasks

CLAUDE_CODE_ENABLE_TASKS — Enables the tasks/subagent system for coordinating multiple parallel work streams.

Affects token usage. Tasks create additional messages and context for coordination.

Experimental Agent Teams

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS — Enables experimental multi-agent teams for collaborative work between agents.

Affects token usage. Adds team coordination messages and context, multiplying token consumption.

Plan Mode Interview Phase

CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE — Controls interview/planning phase behaviour in plan mode.

Affects token usage. Adds interview dialogue and planning context to the conversation.

Plan Mode Required

CLAUDE_CODE_PLAN_MODE_REQUIRED — Forces plan mode to be active. Plan mode adds system prompts and attachments for structured planning.

Affects token usage. Adds plan mode system prompts and planning attachments.

Plan V

CLAUDE_CODE_PLAN_V — Version selector for the plan mode implementation. Different versions may have different token overhead.

Task List Id

CLAUDE_CODE_TASK_LIST_ID — Specifies which task list to use for task management. Routing only.

Provider Routing

Flags for routing API calls through different cloud providers. These change where requests go, not how many tokens they consume.

Provider Managed By Host

CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST — Indicates that provider selection is managed by the host or IDE integration rather than by the user.

Use Bedrock

CLAUDE_CODE_USE_BEDROCK — Routes API calls through AWS Bedrock instead of the direct Anthropic API.

Use Ccr V

CLAUDE_CODE_USE_CCR_V — Version selector for CCR (Claude Code Runtime/Router). Infrastructure versioning.

Use Foundry

CLAUDE_CODE_USE_FOUNDRY — Routes API calls through Anthropic Foundry, the enterprise platform.

Use Vertex

CLAUDE_CODE_USE_VERTEX — Routes API calls through Google Cloud Vertex AI.

Bedrock Base Url (Anthropic)

ANTHROPIC_BEDROCK_BASE_URL — Sets the AWS Bedrock endpoint URL for Claude via Bedrock.

Foundry Api Key (Anthropic)

ANTHROPIC_FOUNDRY_API_KEY — API key for Anthropic Foundry.

Foundry Auth Token (Anthropic)

ANTHROPIC_FOUNDRY_AUTH_TOKEN — Auth token for Anthropic Foundry.

Foundry Base Url (Anthropic)

ANTHROPIC_FOUNDRY_BASE_URL — Foundry API endpoint URL.

Foundry Resource (Anthropic)

ANTHROPIC_FOUNDRY_RESOURCE — Specifies the Foundry resource/workspace identifier.

Vertex Base Url (Anthropic)

ANTHROPIC_VERTEX_BASE_URL — Google Vertex AI endpoint URL for Claude.

Vertex Project Id (Anthropic)

ANTHROPIC_VERTEX_PROJECT_ID — GCP project ID required for Vertex AI access.

Remote and Containers

Flags for remote development, containers, and workspace mapping. None affect token usage.

Container Id

CLAUDE_CODE_CONTAINER_ID — Identifies the container when running in a containerised environment.

Environment Kind

CLAUDE_CODE_ENVIRONMENT_KIND — Specifies the environment type: local, remote, container, etc.

Environment Runner Version

CLAUDE_CODE_ENVIRONMENT_RUNNER_VERSION — Version identifier for the environment runner.

Host Platform

CLAUDE_CODE_HOST_PLATFORM — Overrides the detected host OS platform.

Remote

CLAUDE_CODE_REMOTE — Indicates that remote development mode is active.

Remote Environment Type

CLAUDE_CODE_REMOTE_ENVIRONMENT_TYPE — Specifies the type of remote environment (SSH, container, etc.).

Remote Send Keepalives

CLAUDE_CODE_REMOTE_SEND_KEEPALIVES — Enables keepalive packets for remote connections to prevent timeouts.

Remote Session Id

CLAUDE_CODE_REMOTE_SESSION_ID — Identifies the remote session instance.

Workspace Host Paths

CLAUDE_CODE_WORKSPACE_HOST_PATHS — Maps workspace paths between host and container/remote environments.

Sandbox and Security

Flags for sandboxing, isolation, and security checks. None affect token usage.

Additional Protection

CLAUDE_CODE_ADDITIONAL_PROTECTION — Enables additional security layers beyond standard sandboxing. Exact protections vary by platform.

Bash Sandbox Show Indicator

CLAUDE_CODE_BASH_SANDBOX_SHOW_INDICATOR — When enabled, shows a visual indicator that commands are running in sandbox mode by changing the tool name to SandboxedBash.

Bubblewrap

CLAUDE_CODE_BUBBLEWRAP — Enables bubblewrap-based sandboxing on Linux systems. Uses namespace-based isolation via the bubblewrap tool.

Disable Command Injection Check

CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK — Disables security checks that detect potential command injection attempts in tool calls.

Force Sandbox

CLAUDE_CODE_FORCE_SANDBOX — Forces all bash commands to run in sandbox mode regardless of other settings or permissions.

Search and File System

Flags controlling file search behaviour and file read limits. The file read token cap is a key lever for context size.

File Read Max Output Tokens

CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS — Sets the maximum token limit for file read operations. Default is around 25,000 tokens. Files exceeding this limit are truncated or require targeted reads.

Affects token usage. Directly controls how much file content is sent to the model as input tokens.

Glob Hidden

CLAUDE_CODE_GLOB_HIDDEN — When enabled (default: true), glob/file search operations include hidden files (dotfiles) in results.

Glob No Ignore

CLAUDE_CODE_GLOB_NO_IGNORE — When enabled (default: true), glob operations ignore .gitignore and similar ignore files, returning all matches.

Glob Timeout Seconds

CLAUDE_CODE_GLOB_TIMEOUT_SECONDS — Timeout in seconds for ripgrep-based glob/search operations. Default is 20 seconds on most systems, 60 on WSL.

Session and Lifecycle

Flags for shell configuration, session management, and startup behaviour.

Action

CLAUDE_CODE_ACTION — Specifies a startup action or command to execute when the session begins.

Dont Inherit Env

CLAUDE_CODE_DONT_INHERIT_ENV — Prevents inheriting environment variables from the parent process. Provides a clean environment for the session.

Entrypoint

CLAUDE_CODE_ENTRYPOINT — Identifies the entrypoint: CLI, IDE, or SDK. Used for telemetry and conditional behaviour.

Git Bash Path

CLAUDE_CODE_GIT_BASH_PATH — Path to Git Bash on Windows systems.

Max Retries

CLAUDE_CODE_MAX_RETRIES — Maximum retry attempts for failed API calls. Fewer retries means less chance of wasted tokens on re-sent requests.

New Init

CLAUDE_CODE_NEW_INIT — Changes the /init command to create multiple CLAUDE.md files and offer skills/hooks setup, instead of creating a single CLAUDE.md with documentation only.

Sessionend Hooks Timeout Ms

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS — Timeout in milliseconds for session-end hooks to complete.

Shell

CLAUDE_CODE_SHELL — Specifies the shell to use for the Bash tool.

Shell Prefix

CLAUDE_CODE_SHELL_PREFIX — Prefix applied to commands run in the shell.

Tmpdir

CLAUDE_CODE_TMPDIR — Overrides the temporary directory path.

Teams and Collaboration

Flags for multi-agent collaboration and cowork features.

Base Ref

CLAUDE_CODE_BASE_REF — Base Git reference for diff comparisons in collaborative workflows.

Is Cowork

CLAUDE_CODE_IS_COWORK — Indicates that cowork/collaboration mode is active. Collaboration features may add coordination context.

Sse Port

CLAUDE_CODE_SSE_PORT — Port for Server-Sent Events connections used by IDE and collaboration features.

Team Name

CLAUDE_CODE_TEAM_NAME — Name of the team for multi-agent collaboration.

Teammate Command

CLAUDE_CODE_TEAMMATE_COMMAND — Command specification for invoking teammate agents.

Use Cowork Plugins

CLAUDE_CODE_USE_COWORK_PLUGINS — Enables cowork-specific plugins. May add plugin-provided context.

Worker Epoch

CLAUDE_CODE_WORKER_EPOCH — Epoch/generation identifier for worker processes in multi-agent setups.

Telemetry and Observability

Flags for analytics, tracing, and metrics collection. None affect token usage except ENABLE_TOKEN_USAGE_ATTACHMENT which adds a small stats attachment per turn.

Datadog Flush Interval Ms

CLAUDE_CODE_DATADOG_FLUSH_INTERVAL_MS — Interval in milliseconds for flushing Datadog metrics.

Disable Nonessential Traffic

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC — Disables non-essential network requests such as analytics and telemetry.

Emit Session State Events

CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS — Enables emitting session state change events for SDK integrations.

Emit Tool Use Summaries

CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES — Enables emitting tool usage summaries to telemetry.

Enable Telemetry

CLAUDE_CODE_ENABLE_TELEMETRY — Master switch for telemetry and analytics collection.

Enable Token Usage Attachment

CLAUDE_CODE_ENABLE_TOKEN_USAGE_ATTACHMENT — Adds token usage statistics as a small attachment in the conversation.

Affects token usage. Adds a small per-turn overhead with token stats.

Enhanced Telemetry Beta

CLAUDE_CODE_ENHANCED_TELEMETRY_BETA — Enables enhanced telemetry features (beta).

Otel Flush Timeout Ms

CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS — Timeout in milliseconds for OpenTelemetry flush operations.

Otel Headers Helper Debounce Ms

CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS — Debounce interval in milliseconds for the OpenTelemetry headers helper.

Otel Shutdown Timeout Ms

CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS — Timeout in milliseconds for OpenTelemetry shutdown.

Tags

CLAUDE_CODE_TAGS — Custom tags attached to telemetry and logging events.

Terminal Multiplexer

Flags for tmux integration. None affect token usage.

Tmux Prefix

CLAUDE_CODE_TMUX_PREFIX — Custom tmux prefix key binding.

Tmux Prefix Conflicts

CLAUDE_CODE_TMUX_PREFIX_CONFLICTS — Handles tmux prefix key conflicts.

Tmux Session

CLAUDE_CODE_TMUX_SESSION — Name of the tmux session to use or create.

Tmux Truecolor

CLAUDE_CODE_TMUX_TRUECOLOR — Enables truecolor support in tmux.

Uncategorised

Flags that don't fit neatly into another group.

Search Hints In List

CLAUDE_CODE_SEARCH_HINTS_IN_LIST — Includes search hints in tool listings. May add hint text to tool descriptions.

Test Fixtures Root

CLAUDE_CODE_TEST_FIXTURES_ROOT — Root directory for test fixtures. A development/testing flag.

Use Powershell Tool

CLAUDE_CODE_USE_POWERSHELL_TOOL — Uses PowerShell instead of the Bash tool on Windows.

Tuning for Cost and Token Savings

With over 150 flags available, it's easy to get lost. If your goal is to reduce token consumption and spend, here are the levers that matter most, ranked roughly by impact.

The Big Wins

Cut thinking tokens. Extended thinking can account for the majority of tokens on complex tasks. CLAUDE_CODE_DISABLE_THINKING eliminates them entirely. If that's too aggressive, CLAUDE_CODE_EFFORT_LEVEL set to low or medium dials it back without removing it, and CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING switches from dynamic budgets to fixed ones, giving you more predictable spend.

Shrink the system prompt. Every conversation starts with a system prompt that includes CLAUDE.md files, git instructions, tool definitions, and more. CLAUDE_CODE_DISABLE_CLAUDE_MDS is the nuclear option — it drops all CLAUDE.md content. CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS strips the git workflow guide. CLAUDE_CODE_DISABLE_ADVISOR_TOOL and CLAUDE_CODE_DISABLE_ATTACHMENTS remove tool definitions and attachment overhead respectively. If you have specific heavy CLAUDE.md files, the claudeMdExcludes setting in settings.json lets you surgically exclude them without disabling the entire system.

Use cheaper models for subagents. CLAUDE_CODE_SUBAGENT_MODEL set to sonnet or haiku routes all delegated agent work to a cheaper model. Pair it with ANTHROPIC_SMALL_FAST_MODEL to also downgrade the model used for internal lightweight tasks like hook evaluation and classification.

Moderate Savings

Control compaction. CLAUDE_CODE_AUTO_COMPACT_WINDOW with a lower value triggers compaction earlier, keeping your context window leaner. CLAUDE_CODE_SM_COMPACT enables session memory compaction which automatically summarises conversation history — a significant reduction on long sessions.

Limit file reads. CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS caps how many tokens a single file read can inject into context. The default is around 25,000 — lowering it forces the model to use targeted reads instead of loading entire files.

Disable auto-memory. CLAUDE_CODE_DISABLE_AUTO_MEMORY stops the auto-memory system from reading and writing to the project memory directory, removing that content from your context window.

Cap output. CLAUDE_CODE_MAX_OUTPUT_TOKENS hard-limits how many tokens the model can generate per response. Useful if you find responses are consistently longer than needed.

Minor Savings

Skip prompt history. CLAUDE_CODE_SKIP_PROMPT_HISTORY avoids loading previous prompt history at session start.

Brief mode. CLAUDE_CODE_BRIEF encourages terser output across the board.

MCP instruction deltas. CLAUDE_CODE_MCP_INSTR_DELTA sends only changes to MCP instructions rather than the full set each time, saving tokens when MCP servers are added or removed during a session.

Example: Cost-Optimised Configuration

Here's a settings.json snippet that pulls most of these levers at once:

{
  "effortLevel": "medium",
  "env": {
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
    "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1",
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet",
    "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "10000",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16000",
    "CLAUDE_CODE_BRIEF": "1",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
  }
}

This keeps the main model on Opus with medium effort, but trims context aggressively and offloads lightweight work to cheaper models. Adjust to taste — the right balance depends on whether you value thoroughness or speed.

Applying Changes with /update-config

You don't need to edit settings.json by hand. Claude Code has a built-in /update-config skill that lets you describe the change you want in plain language. Just type /update-config followed by your request:

  • /update-config set effort level to low
  • /update-config add CLAUDE_CODE_BRIEF=1 to my env vars
  • /update-config use sonnet for subagents
  • /update-config disable auto memory and git instructions

The skill reads your current settings, merges your changes without clobbering existing config, and writes the result. It handles the three settings files (~/.claude/settings.json for global, .claude/settings.json for project, .claude/settings.local.json for local overrides) and will ask you which scope you want if it's ambiguous. It's the fastest way to experiment with different configurations without leaving the conversation.