Support JSONC (JSON with comments) in settings.json

Resolved 💬 4 comments Opened Feb 27, 2026 by dpritchett Closed Mar 3, 2026

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.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗