Feature Request: Add a formal `description` field for comments in `settings.json`

Status Open

Maintainer reply None cached

Activity 12 comments · opened Jul 26, 2025

Title: Feature Request: Add a formal description field for comments in settings.json

Body:

Problem:

The settings.json file is powerful, but because JSON doesn't support comments, it's hard to document why a configuration exists. This makes it difficult for teams to maintain complex settings for hooks, permissions, and other features.

Currently, we use unofficial keys like _comment, which works because the parser ignores them, but it's not a standardized or discoverable solution.

Proposed Solution:

I propose adding an official, optional description key that can be added to any object within settings.json.

This pattern already exists within Claude Code. As documented in en/docs/claude-code/slash-commands/index, custom slash commands use a description field in their YAML frontmatter for this exact purpose.

Adopting the same description key for settings.json would create a consistent and predictable developer experience across all configuration files. The Claude Code parser would be updated to recognize and ignore this key, treating it purely as a documentation field.

Example Usage:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Task",
        "description": "Validates the JSON output from a sub-agent against our protocol schema.",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate_agent_output.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "description": "Allowlist essential CI commands but block all network access.",
    "allow": ["Bash(npm run test:*)"],
    "deny": ["WebFetch"]
  }
}

Benefits:

This small change would greatly improve the maintainability and clarity of shared configurations. Most importantly, it would align settings.json with existing configuration patterns in Claude Code, making the entire tool more consistent and intuitive for teams to manage.

View original on GitHub ↗

11 Comments

PaulRBerg · 1 year ago

Or better yet, support jsonc extension

PaulRBerg · 10 months ago

hey @coygeek and Anthropic team, could you please add support for jsonc extension?

The implementation should be super easy but the benefit would be big - my settings.json file has grown quite large and I would very much appreciate the ability to use comments to explain my settings!

vmandela-ti · 9 months ago

Adding support for jsonc would greatly help in reviewing and sharing settings files.

bengous · 9 months ago

I built a plugin that solves this: claude-settings-manager

It lets you maintain __settings.jsonc (with full comment support) and auto-generates settings.json via git hooks.

Features:

Full JSONC support (// and / / comments)
Auto-sync on commit via lefthook/husky
Blocks direct edits to settings.json to prevent drift
AI-powered error explanations when validation fails
Works with regular projects, chezmoi dotfiles, or stow

Not a replacement for native support, but a working solution until then.

PaulRBerg · 9 months ago

I've also rolled my own solution which is a little more advanced than @bengous's manager - sharing in case anyone finds it useful:

I isolate each section of the settings.json into a separate *.jsonc, file, e.g., settings/hooks.jsonc
I run this merge_settings.sh bash script for merging all JSONs into settings.json
I use lint-staged to run the merge script upon every commit in my .claude repo

Link: https://github.com/PaulRBerg/dot-claude

github-actions[bot] · 7 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

PaulRBerg · 7 months ago

Please keep open and add support for jsonc

mieubrisse · 7 months ago

Definitely would appreciate this, especially as settings.json files grow more complex

PaulRBerg · 7 months ago

Created a dedicated issue for JSONC support as an alternative approach: #17968

coygeek · 7 months ago

Hey everyone, following up on my previous request. I’ve been keeping an eye on the daily documentation updates at code.claude.com, and I wanted to share what I found in the latest version (as of Jan 16, 2026).

It looks like this has been partially implemented, specifically for Hooks and Plugins, but it hasn't yet been formalized as a global field for all objects (like Permissions).

What’s been updated:

In the new Hooks Reference (docs/en/hooks.md), there is a new section for Plugin Hooks that explicitly mentions this:

"Plugin hooks use the same format as regular hooks with an optional description field to explain the hook's purpose."

The documentation even includes an example of a hook object using the key:

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [ ... ]
  }
}

What’s still missing:

While it's great to see description appearing in the hooks and plugin schemas, it hasn't been added to the official Settings reference (docs/en/settings.md) yet.

The Available Settings table for settings.json still doesn't list description as a supported top-level key.
The Permission Settings table still only lists allow, ask, deny, etc., without a formal description field.

Summary: We're halfway there! The parser clearly supports description for hooks now, which is a huge win for maintaining complex automation. I'm hoping to see the team extend this to the permissions object and other areas of settings.json to match the consistency of the custom slash command YAML frontmatter.

I'll leave this issue open until it's officially supported across the entire settings.json schema!

frakon · 3 months ago

Created a dedicated issue for JSONC support as an alternative approach: #17968

Supporting comments fully is much better solution than "description" tag: faster edits (commenting, uncommenting, writing new explanatory comments) + user can use what he is used to from other json settings files (most of which support comments).

Showing cached comments. Read the full discussion on GitHub ↗