Support JSONC (JSON with comments) in settings.json
Problem
settings.json files grow complex as users add permission rules, hooks, plugins, and status line config. There's no way to document why a rule exists inline — you have to maintain a separate file or rely on a templating tool like chezmoi to keep comments in a source file that renders to plain JSON.
For example, a permission allow list with 20+ entries benefits from grouping and annotation:
{
"permissions": {
"allow": [
// Read-only git commands (no destructive flags, no embedded interpreters)
"Bash(git status)",
"Bash(git log *)",
"Bash(git diff *)",
"Bash(git show *)",
// CLI tools (read-only, no network)
"Bash(jq:*)",
"Bash(yq:*)",
"Bash(bat:*)",
// Project-specific tooling (pre-approved safe binaries)
"Bash(terraform plan *)",
"Bash(kubectl get *)"
]
}
}
Without comments, the rationale for each group is lost. Users either under-document their security decisions or move to external tooling just to get comments.
Proposal
Parse settings.json (and settings.local.json) as JSONC — JSON with // and /* */ comments stripped before parsing. This is the same format VS Code uses for its settings.json, so the convention is well-established in the developer tools space.
No new file extension needed. Standard .json files that happen to contain comments just work. Files without comments continue to parse identically.
Alternatives considered
- Separate documentation file: Works but disconnects the explanation from the rule it describes.
- Chezmoi/templating: Effective but adds a build step and tooling dependency just to get comments.
- YAML or TOML config: Bigger migration, comments are just one benefit.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗