[DOCS] VS Code page does not explain distinction between extension settings and Claude Code settings

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/vs-code

Section/Topic

The "Configure settings" section on the VS Code extension page.

Current Documentation

The "Configure settings" section states:

The extension has two types of settings: - Extension settings in VS Code: Control the extension's behavior within VS Code. Open with Cmd+, (Mac) or Ctrl+, (Windows/Linux), then go to Extensions → Claude Code. - Claude Code settings in ~/.claude/settings.json: Shared between the extension and CLI. Use for allowed commands, environment variables, hooks, and MCP servers.

This is followed by the extension settings table. There is no further explanation of when to use which system, what overlaps, or what happens when the same concept is configured in both.

What's Wrong or Missing?

The two-bullet summary is accurate but insufficient for users who need to configure Claude Code. Specific gaps:

A. Overlapping concepts not addressed

Some settings exist in both systems with different keys. For example:

• Model selection: claudeCode.selectedModel (VS Code) vs model (settings.json) — which takes precedence?
• Permission mode: claudeCode.initialPermissionMode (VS Code) vs permissions.defaultMode (settings.json) — are these the same?
• Git ignore: claudeCode.respectGitIgnore (VS Code) vs respectGitignore (settings.json) — note the different casing

The docs don't explain which takes precedence when both are set, or whether they're truly equivalent.

B. No guidance on which system to use

A user wanting to configure their model has two options: the VS Code setting or settings.json. The docs don't explain why they'd choose one over the other. The key difference — that settings.json is shared with the CLI — is mentioned once but not emphasized as a decision factor.

C. Environment variables add a third layer

The model config page documents ANTHROPIC_MODEL as another way to set the model. Combined with the two settings systems, users face three overlapping configuration paths with no unified precedence explanation on the VS Code page.

Suggested Improvement

Expand the "Configure settings" section with a brief decision guide:

Suggested addition after the existing two bullets:

When to use each: | Want to configure... | Use | Why | |---------------------|-----|-----| | Extension UI behavior (panel location, autosave, terminal mode) | VS Code extension settings | These are VS Code-specific and don't apply to the CLI | | Permissions, hooks, MCP servers, environment variables | Claude Code settings.json | Shared between extension and CLI; supports project/team scopes | | Model selection | Either — settings.json is recommended if you also use the CLI | Extension setting applies to VS Code only | When the same setting is configured in both VS Code extension settings and settings.json, Claude Code settings.json takes precedence for shared settings.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Issue |
|------|-------|
| https://code.claude.com/docs/en/vs-code | "Configure settings" section lacks decision guide and precedence rules |
| https://code.claude.com/docs/en/settings | Documents settings.json thoroughly but doesn't reference VS Code extension settings |

Total scope: 2 pages affected

This is especially confusing for users who start with the VS Code extension and later adopt the CLI. They may have configured settings in VS Code that don't carry over to the CLI, with no documentation explaining why.