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

[coygeek]

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.

[github-actions]

Found 3 possible duplicate issues:

1. [Feature Request] Document configuration file structure and directory hierarchy rationale #24005
2. [DOCS] No documentation for disabling auto-compaction #24589
3. [DOCS] No centralized reference for all Claude Code files and directories on disk #26168

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[coygeek]

Issue #26167 Verification

Title: [DOCS] Settings page: ~/.claude.json configuration file gets one sentence of documentation
Issue Date: 2026-02-16
Verification Date: 2026-03-17
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports that ~/.claude.json received only one sentence of documentation, insufficient for a file that stores preferences, OAuth, MCP configs, per-project state, and caches.

---

Verification Results

Claim 1: ~/.claude.json barely documented

Status: PARTIALLY RESOLVED

At https://code.claude.com/docs/en/settings, the file now has a more substantive description:

"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."

It also appears in the scope table as the location for user-scope MCP servers.

However, there is still no schema, field-level documentation, or guidance on directly editing the file. The description enumerates what it stores but doesn't explain individual fields or structure.

Verdict: Improved from a single sentence to a paragraph that enumerates stored data categories. Still lacks schema or field-level detail.

---

Current State

Claim	Status
Only one sentence of docs	PARTIALLY RESOLVED — now a full paragraph
No schema or field-level docs	UNRESOLVED

---

References

• URL: https://code.claude.com/docs/en/settings (Other configuration bullet)

---

Conclusion & Recommendation

Primary Concern: ~/.claude.json was barely documented.

Resolution Status: PARTIALLY RESOLVED

Recommendation: KEEP OPEN

The description is improved but still lacks schema or field-level documentation for a file that stores significant configuration state.

[coygeek]

Correction after a full re-verification on 2026-04-01: this issue is still only partially resolved, not resolved. The docs now distinguish ~/.claude.json from ~/.claude/settings.json and document some global-config keys, but they still do not give one clear reference for which parts of ~/.claude.json are user-editable versus Claude-managed or explain the broader file layout, so this should remain open.

[lewislbr]

Would be great if ~/.claude.json could live inside the .claude folder, as it's easy to miss during backups

[coygeek]

Issue #26167 Verification

Title: [DOCS] Settings page: ~/.claude.json configuration file gets one sentence of documentation
Issue Date: 2026-02-16
Verification Date: 2026-04-28
Status: RESOLVED

---

Issue Summary

This issue reports that the settings documentation gave ~/.claude.json only a brief description, did not clearly distinguish it from ~/.claude/settings.json, did not explain when users should interact with each file, and did not document enough of ~/.claude.json's structure and per-project organization.

---

Verification Results

Claim 1: The docs did not clearly distinguish ~/.claude.json from ~/.claude/settings.json

Status: RESOLVED

At https://code.claude.com/docs/en/settings, lines 66-71: | **Settings** | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json | and | **MCP servers** | ~/.claude.json | .mcp.json | ~/.claude.json (per-project) |.

At https://code.claude.com/docs/en/debug-your-config, line 75: ``/.claude.jsonholds app state and UI toggles.permissions`, `hooks`, and `env` belong in `/.claude/settings.json`. These are two different files.`

Verdict: The current docs now explicitly separate the two files by purpose and location, and they directly state that they are different files.

---

Claim 2: The docs did not explain when users should interact with each file

Status: RESOLVED

At https://code.claude.com/docs/en/claude-directory, lines 420-421: Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change settings in /config or approve trust prompts and Holds state that does not belong in settings.json: theme, OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. Mostly managed through /config rather than editing directly.

At https://code.claude.com/docs/en/debug-your-config, line 75: ``/.claude.jsonholds app state and UI toggles.permissions`, `hooks`, and `env` belong in `/.claude/settings.json`.`

At https://code.claude.com/docs/en/settings, lines 238-239: These settings are stored in ~/.claude.json rather than settings.json. Adding them to settings.json will trigger a schema validation error.

Verdict: The current docs now explain that ~/.claude.json is mostly Claude Code-managed state, while user-editable configuration such as permissions, hooks, and environment variables belongs in settings.json.

---

Claim 3: The docs did not document the structure, keys, or per-project organization of ~/.claude.json

Status: RESOLVED

At https://code.claude.com/docs/en/settings, lines 236-248: ### Global config settings, These settings are stored in ~/.claude.json rather than settings.json. Adding them to settings.json will trigger a schema validation error., and the table entries for autoConnectIde, autoInstallIdeExtension, and externalEditorContext.

At https://code.claude.com/docs/en/mcp, lines 436-450: Claude Code stores it in ~/.claude.json under that project's path and The command writes the server into the entry for your current project inside ~/.claude.json.

At https://code.claude.com/docs/en/mcp, lines 452-464: the example shows the per-project structure under "projects" with a nested project path and "mcpServers" object.

At https://code.claude.com/docs/en/claude-directory, lines 421-422: Holds state that does not belong in settings.json: theme, OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. and The projects key tracks per-project state like trust-dialog acceptance and last-session metrics.

Verdict: The current docs now include a dedicated global-config section, name specific ~/.claude.json keys, and show how per-project data is organized under the projects key.

---

Current State

Claim	Status
The docs did not clearly distinguish ~/.claude.json from ~/.claude/settings.json	RESOLVED
The docs did not explain when users should interact with each file	RESOLVED
The docs did not document the structure, keys, or per-project organization of ~/.claude.json	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/settings
• Lines 66-71: Distinguishes settings files from MCP server storage locations.
• URL: https://code.claude.com/docs/en/settings
• Lines 117-120: Summarizes what ~/.claude.json stores and notes automatic backups.
• URL: https://code.claude.com/docs/en/settings
• Lines 236-248: Adds a Global config settings section with documented ~/.claude.json keys.
• URL: https://code.claude.com/docs/en/debug-your-config
• Lines 70-76: Explains that ~/.claude.json and ~/.claude/settings.json are different files with different roles.
• URL: https://code.claude.com/docs/en/claude-directory
• Lines 420-422: States that ~/.claude.json is mostly managed through /config and describes the projects key.
• URL: https://code.claude.com/docs/en/mcp
• Lines 436-464: Explains and shows the per-project projects structure inside ~/.claude.json for local-scoped MCP servers.

---

Conclusion & Recommendation

Primary Concern: The issue reported that ~/.claude.json was under-documented and insufficiently distinguished from ~/.claude/settings.json.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current documentation now distinguishes the two files, explains that ~/.claude.json is mostly Claude Code-managed state, and documents both example keys and the per-project structure stored inside it. The reported documentation gap has been addressed.

---

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.