[FEATURE] Support JSONC format for settings files (settings.jsonc)

Adding that this would be very useful for me - my settings.json is starting to get large, and I'd like to document why I made certain deny choices. Since deny is an array (not an object), the "use a key like // for comments" approach doesn't work.

need this too~

+1

We'd greatly value having this feature, especially in Enterprise settings, where the leadership team can create comments on the settings.jsonc that plainly emphasise what means what and why it matters.

+1, having comments in configuration files is important, especially when using in a team environment where you are trying to get everyone on the same page.

+1

Alternatively, supporting YAML or TOML would make the config easier to manage as well (and support comments natively)

+1!! it'd be great have inline documentation of permission groups

Amen to YAML. In our codebase, our rule is YAML for configs, and JSON only for data serialization.

if you do keep json as the configuration language, maybe you should just skip directly to json5?

Personally, I'd prefer keeping settings.json (not settings.jsonc or settings.json5) for backward compatibility but allow comments. That's what VS Code does with _jsonc_ mode.

Amen to YAML. In our codebase, our rule is YAML for configs, and JSON only for data serialization.

Oh no, YAML is a horrible choice.

Adding my voice here — this is one of those small changes that would have an outsized impact on daily workflow.

As someone who maintains fairly complex settings across user, project, and local scopes (hooks, permissions, MCP servers, env vars), the inability to annotate why a particular rule exists is a real pain point. I end up keeping the rationale in my head or in a separate doc that inevitably drifts out of sync. The _comment hack is already ugly and fragile — no guarantee it won't break if schema validation gets stricter — but as others have noted, it doesn't even work in arrays. Permission lists and hook arrays are exactly the places where you most need to document intent, and _comment keys simply can't go there.

JSONC is the established standard for exactly this use case. VS Code, tsconfig.json, devcontainer.json — the tooling ecosystem has already converged on it. Packages like strip-json-comments or jsonc-parser (the one VS Code itself uses) make this trivial to implement. The surface area is genuinely small:

1. Strip comments before JSON.parse() (or use a JSONC parser)
2. Check for settings.jsonc first, fall back to settings.json

No schema changes, no new features to document beyond "you can now use comments." This would be a huge quality-of-life win for everyone managing non-trivial configurations. Please prioritize this one — it's low effort, high reward, and long overdue.

We have a similar issue sharing enterprise managed settings files. Our current solution is to have a CI job that asserts that every setting in the managed settings file is documented in README.md. The ability to use inline comments would be extremely useful. Partly for the managed settings repo maintainers / auditors, but partly because a user whose action is blocked by the sandbox would be able to ask Claude why it's blocked and get a meaningful response as Claude can read the comments in the file.

+1 to TOML, +0.5 to JSON5. There's not really a reason to use old-school JSON instead of JSON5 nowadays given JSON5 is a superset and has fewer weird edge-cases.

+1

I'd appreciate the ability to add comments as well. It might make the most sense to do JSONC first, since it'd be such a small change. Then could consider JSON5 or YAML or something else later as additional options.

Then could consider JSON5

JSON5 is a standardized/documented version of JSONC (which explicitly allows trailing commas and single-quoted strings, as in JS).

Come on Anthropic, what is so hard about switching the parser to JSONC? @coygeek

Ask Claude.

+1 please do this. or support yaml or toml.

Check for settings.jsonc first, fall back to settings.json

I understand the intuition, but I'd recommend not allowing more than one accepted settings.json variant.

Instead, being permissive with setting.json and stripping comments on parse would make sense. It is fully backwards compatible, and doesn't create the need to prioritize or reconcile multiple settings files, and there's already general precedent all over for parsing json files as jsonc in numerous widely used tools anyways (e.g. the VSCode example).

I also think keeping this issue on topic and narrowly focused on how to handle comments in settings.json is the right move. Discussion on TOML, YAML, or JSON5 are separate concerns and best suited as dedicated issues.

jsonc also supports trailing commas
which makes version control diffs cleaner
and editing might be less troublesome

A workaround that needs no format change: keep the file strict JSON and put the "why" in a JSON Schema your editor binds to it.

• Describe each key in a schema (for settings.json the official one at json.schemastore.org/claude-code-settings.json is a usable base — copy it and rewrite the descriptions in your own words, or your own language).
• Bind it from the editor side, e.g. VS Code's json.schemas with a fileMatch glob and a local file:/// URL, so the config file itself stays annotation-free.
• This covers the case _comment can't: array entries (permission rules, hooks) are documented by their subschema, and nothing has to live inside the array.
• Side benefit: descriptions can be written in any language, so the hover text reads in yours.

Two limits worth knowing: it is hover-only, so anyone reading the raw file in a terminal still sees nothing; and it needs a schema to exist or to be written by hand.

Writing $schema into a config file that an application owns is not a workaround: apps may log "not a recognized configuration key" and drop the key on their next write (observed with Claude Desktop's own config file).

🤖 Generated with Claude Code