Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Document the `projects` Key Schema in `~/.claude.json` [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#51718•Fetched 2026-04-22 07:54:42
View on GitHub
Comments
1
Participants
2
Timeline
4
Reactions
0
Author
JimwoodwardJimwoodward
Participants
github-actions[bot]github-actions[bot]JimwoodwardJimwoodward
Timeline (top)
labeled ×3commented ×1
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

No response

Section/Topic

Claude Code Settings Files

Current Documentation

https://code.claude.com/docs/en/claude-directory#ce-claude-json -- This is the only documentation I can find on the ~/.claude.json file.

What's Wrong or Missing?

There are certain aspects of the ~/.claude.json file that don't make sense to document as they appear to be some kind of feature flagging that is centrally and remotely managed. However, the projects key does not appear to be one of those aspects.

Instead, this key has many entries that are either directly or indirectly controlled by actions that I take when I use claude. e.g. claude mcp add ... and the mcpServers key (explicit) or by accepting the dialog/prompt asking if I trust the directory I have started Claude in and the hasTrustDialogAccepted key (implicit).

It would be nice if these keys and values were documented in more depth. Since projects are essentially just directories where Claude has been initiated, and since the information in the ~/.claude.json file has no mechanism for being cleaned up from stale information, it is not far fetched to imagine a scenario where I revisit a directory to begin working after a very long time and certain settings and permissions that were previously applied do not make sense to still be applied (the alternate fix here is to decouple the concept of a projects from a directory on the local file system, but that is clearly a massive ask and out of scope). If Claude isn't going to prune certain fields here for me, I would like to be equipped with the knowledge to do the pruning myself.

Suggested Improvement

  1. Document the projects key of ~/.claude.json
  2. (optional, but preferred) Document the entire ~/.claude.json file. Make caveats for keyspaces that appear to be intentionally obscure e.g. everything in the cachedGrowthBookFeatures key

Impact

Medium - Makes feature difficult to understand

Additional Context

No response

extent analysis

TL;DR

Documenting the projects key in the ~/.claude.json file would provide clarity on its usage and allow users to manage stale information.

Guidance

  • Review the current documentation at https://code.claude.com/docs/en/claude-directory#ce-claude-json to understand the existing structure of the ~/.claude.json file.
  • Investigate the projects key and its relationship with Claude's functionality, such as the claude mcp add command and the mcpServers key.
  • Consider documenting the entire ~/.claude.json file, while making note of intentionally obscure keyspaces like cachedGrowthBookFeatures.
  • Evaluate the need for a mechanism to clean up stale information in the ~/.claude.json file to prevent outdated settings and permissions.

Example

No code snippet is provided as the issue focuses on documentation rather than code implementation.

Notes

The solution relies on the assumption that documenting the projects key and potentially the entire ~/.claude.json file will address the user's concerns about understanding and managing the file's contents.

Recommendation

Apply workaround: Document the projects key and consider documenting the entire ~/.claude.json file to provide clarity and allow users to manage stale information. This approach addresses the user's immediate concerns and provides a foundation for further improvements.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#agent setup#task chaining#parallel task#integration issue#index setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING