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:
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.
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:
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:
claudeCode.selectedModel(VS Code) vsmodel(settings.json) — which takes precedence?claudeCode.initialPermissionMode(VS Code) vspermissions.defaultMode(settings.json) — are these the same?claudeCode.respectGitIgnore(VS Code) vsrespectGitignore(settings.json) — note the different casingThe 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 — thatsettings.jsonis 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_MODELas 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:
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
settings.jsonthoroughly but doesn't reference VS Code extension settingsTotal 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.