claude-code - 💡(How to fix) Fix [DOCS] Document feature-flag and bootstrap cache behavior when opt-out variables are enabled

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/env-vars https://code.claude.com/docs/en/data-usage https://code.claude.com/docs/en/claude-directory https://code.claude.com/docs/en/debug-your-config

Section/Topic

Feature-flag, bootstrap, and client-data cache lifecycle when DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set

Current Documentation

The environment variable reference currently says:

DISABLE_GROWTHBOOK | Set to 1 to disable GrowthBook feature-flag fetching and use code defaults for every flag. Telemetry event logging stays on unless DISABLE_TELEMETRY is also set

It also says:

DISABLE_TELEMETRY | Set to 1 to opt out of telemetry. Telemetry events do not include user data like code, file paths, or bash commands. Also disables feature-flag fetching with the same effect as DISABLE_GROWTHBOOK, so some flagged features may be unavailable

And:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY

The data-usage page currently says:

You can opt out of all non-essential traffic, including surveys, at once by setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. This variable does not affect the WebFetch check, which has its own opt-out.

What's Wrong or Missing?

The docs explain that feature-flag fetching can be disabled and that code defaults are used, but they do not explain what happens to feature-flag, bootstrap, or client-data values that were already cached locally before the opt-out variable was enabled.

Users need to know whether enabling an opt-out variable:

• prevents only new remote fetches;
• also ignores existing cached GrowthBook or bootstrap values;
• deletes cached values;
• requires a manual cache clear to return to code defaults;
• affects bootstrap/client-data fetches in addition to GrowthBook feature-flag fetches.

This matters for privacy and behavior debugging. A user may run Claude Code without opt-out variables, receive cached remote configuration, then later add DISABLE_GROWTHBOOK=1, DISABLE_TELEMETRY=1, or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and reasonably expect code defaults to apply immediately. The docs currently do not confirm whether that expectation is correct.

The same ambiguity applies to the word "nonessential." The env-vars page defines CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC by listing four other variables, but the data-usage page describes it more broadly as disabling all non-essential traffic. The docs do not say whether bootstrap/client-data fetches are considered nonessential traffic, required traffic, or a separate class.

Suggested Improvement

Add a cache-lifecycle note near the relevant environment variables and cross-link it from data-usage and application-data documentation.

Suggested coverage:

• State whether DISABLE_GROWTHBOOK=1 and DISABLE_TELEMETRY=1 ignore existing cached feature-flag values or only stop future fetches.
• State whether CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 affects bootstrap/client-data requests.
• State whether bootstrap/client-data values are cached, where they are stored, and how users can clear them.
• If cached values remain in effect after an opt-out variable is added, document the manual cleanup steps needed to return to built-in defaults.
• If cached values are ignored after opt-out, document that guarantee explicitly.

Possible wording:

DISABLE_GROWTHBOOK=1 and DISABLE_TELEMETRY=1 stop remote feature-flag fetching and make Claude Code use built-in defaults. Existing cached feature-flag values are [ignored/deleted/still used until cleared]. To clear cached feature flags manually, remove [documented cache path]. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 [does/does not] also disable bootstrap/client-data fetches.

Impact

Medium - Makes feature difficult to understand

Additional Context

This is related to, but narrower than:

• https://github.com/anthropics/claude-code/issues/47558

That issue asks the docs to explain that disabling telemetry also disables experiment gates and falls back to defaults.

This draft asks the docs to define the cache lifecycle: what happens to already-cached gate/bootstrap/client-data values after opt-out variables are set.

The ambiguity also appeared in:

• https://github.com/anthropics/claude-code/issues/62061

The reporter claimed:

Cached feature values persisted to disk from a prior unguarded session are still read.

I am not asking the docs to accept that exact claim without verification. I am asking for the intended, current cache behavior to be documented so users can reason about opt-out controls and debug behavior drift across sessions.