›_ Claude Code Issues
Claude Code Issues / #26167

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

Status Fixed / completed
Maintainer reply None cached
Activity 6 comments · opened Feb 16, 2026 · closed Apr 29, 2026

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.

View original on GitHub ↗

6 Comments

github-actions[bot] · 6 months ago

Found 3 possible duplicate issues:

  1. https://github.com/anthropics/claude-code/issues/24005
  2. https://github.com/anthropics/claude-code/issues/24589
  3. https://github.com/anthropics/claude-code/issues/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 · 5 months ago

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

---

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 · 5 months ago

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 · 4 months ago

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

coygeek · 4 months ago

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.json holds 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.json holds 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

---

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[bot] · 3 months ago

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.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Same class of failure, ranked by community engagement — this issue is one of many, so it may not appear in the visible list: Authentication & login failures, MCP server connection issues

Browse all Claude Code issue topics →