[FEATURE] Support JSONC format for settings files (settings.jsonc)
Open 💬 18 comments Opened Jan 13, 2026 by PaulRBerg
Problem
JSON doesn't support comments, making it difficult to document configuration decisions in settings.json. As noted in #4475, users resort to unofficial keys like _comment for documentation purposes.
Rather than adding a custom description field, a more standard solution would be to support JSONC (JSON with Comments) - the same format used by VS Code's settings.json, tsconfig.json, and many other developer tools.
Proposed solution
- Update the settings parser to accept JSONC syntax (allow
//and/* */comments) - Optionally support
settings.jsoncas an alternative filename (with precedence oversettings.json) - Update documentation to reflect JSONC support
Example usage:
{
"hooks": {
"PostToolUse": [
{
// Validates JSON output from sub-agents against our protocol schema
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/validate_agent_output.sh"
}
]
}
]
},
"permissions": {
// Allowlist essential CI commands but block all network access
"allow": ["Bash(npm run test:*)"],
"deny": ["WebFetch"]
}
}Alternatives considered
- Custom
descriptionfield (#4475): Works but non-standard; requires Claude Code-specific parsing and doesn't match how other tools handle JSON configuration _commentkeys: Currently works since unknown keys are ignored, but undocumented and inconsistent
Priority
Medium
Category
Configuration and settings
18 Comments
Adding that this would be very useful for me - my
settings.jsonis starting to get large, and I'd like to document why I made certaindenychoices. Sincedenyis 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.jsoncthat 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(notsettings.jsoncorsettings.json5) for backward compatibility but allow comments. That's what VS Code does with _jsonc_ mode.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
_commenthack 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_commentkeys 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-commentsorjsonc-parser(the one VS Code itself uses) make this trivial to implement. The surface area is genuinely small:JSON.parse()(or use a JSONC parser)settings.jsoncfirst, fall back tosettings.jsonNo 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.
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.