[FEATURE] Support JSONC (comments) in settings.json

Preflight Checklist

• [x] I have searched existing requests — closest matches are #4475 (open), plus #29370 and #12688, both closed as duplicates of it. Filing separately because the ask here is specifically JSONC syntax rather than a description field; happy for it to be folded into #4475 if maintainers see them as the same request.
• [x] This is a single feature request (not multiple features)

Problem Statement

~/.claude/settings.json is a hand-maintained file that many people keep in a dotfiles repo, but there is no way to record why a setting is set. Things like "defaultMode": "bypassPermissions", a pinned model, or an entry in env are exactly the settings a future reader — or a teammate reviewing the dotfiles PR — needs context for, and the file format offers nowhere to put it.

Comments aren't merely absent, they're rejected. Adding a // line produces:

Invalid settings
- /home/user/.claude/settings.json: Invalid or malformed JSON

so the whole file is discarded rather than the comment ignored. Renaming to settings.jsonc doesn't help either — that filename isn't read at all, so every setting silently reverts to its default, which is a quiet and fairly unpleasant failure mode.

This is out of step with the neighbouring files developers edit: VS Code's settings.json, tsconfig.json, and devcontainer.json all accept comments, and several other coding agents read a .jsonc config.

Proposed Solution

Parse settings.json as JSONC — strip comments (and ideally tolerate trailing commas) before JSON.parse. settings.json keeps its name, existing files stay valid since JSON is a subset, and no schema change is needed.

{
  // Bypass prompts: this machine is a disposable WSL dev box.
  "permissions": { "defaultMode": "bypassPermissions" },

  // Blocks the VS Code extension auto-install on launch.
  "env": { "CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL": "1" }
}

Accepting settings.jsonc as an alternative filename would also work, but reusing settings.json seems preferable — it avoids splitting the config across two possible names.

Alternative Solutions

There's a workaround that works today: because the settings schema is a passthrough object, unknown keys are preserved rather than rejected, so "// …" string keys can carry the commentary.

{
  "// permissions": "Bypass prompts: this machine is a disposable WSL dev box.",
  "permissions": { "defaultMode": "bypassPermissions" }
}

These validate cleanly under claude doctor and survive the rewrites Claude Code performs when a setting is changed through /config. But it's an undocumented side effect rather than a supported convention, it would break if the schema were ever tightened to strip unknown keys, and it reads poorly compared to a real comment — the key has to be unique, so it can't simply be // repeated.

Priority

Low - Nice to have

Feature Category

Configuration and settings

Use Case Example

1. ~/.claude/settings.json is committed to a dotfiles repo and restored onto new machines.
2. Six months later, a line in env is no longer self-explanatory, and neither is why permissions are configured the way they are.
3. With JSONC, the reason sits on the line above the setting, and it travels with the file.
4. Today the choice is between losing the context entirely or moving it into a separate README that drifts out of sync with the file it describes.

Additional Context

Verified on 2.1.220 (Ubuntu 24.04 / WSL2):

• a // comment in settings.json → claude doctor reports Invalid or malformed JSON
• settings.jsonc → not read; the settings simply don't apply
• "// …" keys → accepted, and preserved across Claude Code's own writes

Related: #4475 asks for a formal description field for the same underlying problem; #29370 and #12688 asked for comments and were closed as duplicates of it.