[DOCS] Settings page: ~/.claude.json configuration file gets one sentence of documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Settings files" section, specifically the bullet point about ~/.claude.json.

Current Documentation

The file ~/.claude.json receives a single bullet point in the "Settings files" section:

Other configuration is stored in ~/.claude.json. This file contains your preferences (theme, notification settings, editor mode), OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in .mcp.json.

That is the entire documentation for this file.

What's Wrong or Missing?

The ~/.claude.json file is a critical configuration file that stores significant state, yet it shares a confusingly similar name with ~/.claude/settings.json. The documentation does not adequately distinguish them:

A. No distinction between the two files

A user seeing both ~/.claude.json and ~/.claude/settings.json has no clear guide on which file does what. The settings page documents settings.json extensively (available settings table, examples, schema) but gives ~/.claude.json a single sentence.

B. No guidance on when users interact with each

~/.claude/settings.json is user-edited. Is ~/.claude.json also user-edited, or is it managed by Claude Code? The docs don't say. Users don't know whether they should edit this file directly or leave it alone.

C. No structure documentation

The one-sentence description lists what's stored but doesn't explain the file's structure, keys, or how per-project state is organized within it.

Suggested Improvement

Add a dedicated subsection or expand the existing bullet point:

Suggested addition:

### ~/.claude.json This file is primarily managed by Claude Code itself — you generally don't need to edit it directly. It stores: | Category | Examples | |----------|----------| | Preferences | Theme, notification settings, editor mode, vim mode | | Authentication | OAuth session tokens | | MCP servers | User-scope and local-scope (per-project) server configurations | | Per-project state | Previously allowed tools, workspace trust settings | | Caches | Various internal caches | For user-configurable settings (permissions, hooks, environment variables, model selection), use ~/.claude/settings.json instead. Claude Code automatically creates timestamped backups of this file.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Issue |
|------|-------|
| https://code.claude.com/docs/en/settings | ~/.claude.json gets one sentence under "Settings files" |

Total scope: 1 page affected

The confusion between ~/.claude.json and ~/.claude/settings.json is compounded by the fact that MCP server configuration spans both files — user/local-scope MCP servers go in ~/.claude.json while project-scope MCP servers go in .mcp.json. This split is documented on the MCP page but not on the settings page.