claude-code - 💡(How to fix) Fix [DOCS] `settings.json` `env` docs do not explain that `NO_COLOR` and `FORCE_COLOR` should affect subprocesses, not Claude Code's own UI

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

env in the Available settings table and the Environment variables section

Current Documentation

The docs currently say:

env | Environment variables that will be applied to every session | {"FOO": "bar"}

And later:

Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in settings.json under the env key to apply it to every session or roll it out to your team.

The environment variables reference repeats the same guidance:

Claude Code supports the following environment variables to control its behavior. Set them in your shell before launching claude, or configure them in settings.json under the env key to apply them to every session or roll them out across your team.

What's Wrong or Missing?

These pages describe settings.json env as applying environment variables broadly to a session, but they do not explain an important behavior boundary: UI-facing terminal variables such as NO_COLOR and FORCE_COLOR should affect subprocesses only, not Claude Code's own interface rendering.

The changelog for v2.1.143 confirms this user-visible distinction:

Fixed NO_COLOR/FORCE_COLOR in settings.json env stripping Claude Code's own UI colors — they now apply to subprocesses only

Without that clarification, a reader can reasonably expect putting NO_COLOR or FORCE_COLOR in settings.json env to restyle Claude Code itself, when the intended behavior is narrower.

Suggested Improvement

Add a short clarification anywhere settings.json env is described, for example under the env row in Settings and in the intro paragraph on the environment variables page.

Suggested wording:

Variables set in settings.json env are applied to Claude Code session processes and subprocesses, but some terminal-display variables such as NO_COLOR and FORCE_COLOR only affect spawned subprocesses. They do not override Claude Code's own UI colors.

If there is a dedicated way to control Claude Code's interface colors, link to that page from the same note so users do not treat NO_COLOR or FORCE_COLOR as a UI theme setting.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version: v2.1.143