Claude Code Settings Schema

claude-code-settings.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Claude Code Settings",
  "description": "JSON Schema for Claude Code .claude/settings.json configuration files",
  "type": "object",
  "properties": {
    "permissions": {
      "description": "Permission configuration for tool usage and file access",
      "type": "object",
      "properties": {
        "allow": {
          "description": "Array of allowed tool patterns. Format: Tool(pattern) or just Tool",
          "pattern": "^[A-Za-z]+(\\([^)]*\\))?$",
          "examples": [
            "Bash(git diff:*)",
            "Read(src/*)",
            "Write(*.md)",
            "WebFetch"
          ],
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9]*(\\([^)]*\\))?$",
            "description": "Tool permission pattern. Format: ToolName or ToolName(pattern)",
            "examples": [
              "Bash",
              "Read(*.md)",
              "Write(src/*)",
              "WebFetch",
              "Bash(git diff:*)"
            ]
          },
          "title": "allow"
        },
        "deny": {
          "description": "Array of denied tool patterns. Format: Tool(pattern) or just Tool",
          "pattern": "^[A-Za-z]+(\\([^)]*\\))?$",
          "examples": [
            "Read(./.env)",
            "WebFetch",
            "Bash(rm *)"
          ],
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9]*(\\([^)]*\\))?$",
            "description": "Tool permission pattern. Format: ToolName or ToolName(pattern)",
            "examples": [
              "Bash",
              "Read(*.md)",
              "Write(src/*)",
              "WebFetch",
              "Bash(git diff:*)"
            ]
          },
          "title": "deny"
        },
        "ask": {
          "description": "Array of tool patterns that require confirmation. Format: Tool(pattern) or just Tool",
          "pattern": "^[A-Za-z]+(\\([^)]*\\))?$",
          "examples": [
            "Write(*)",
            "Bash(*)",
            "Delete"
          ],
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9]*(\\([^)]*\\))?$",
            "description": "Tool permission pattern. Format: ToolName or ToolName(pattern)",
            "examples": [
              "Bash",
              "Read(*.md)",
              "Write(src/*)",
              "WebFetch",
              "Bash(git diff:*)"
            ]
          },
          "title": "ask"
        }
      },
      "title": "permissions"
    },
    "env": {
      "$ref": "#/definitions/Record<string,string>",
      "description": "Environment variables to set for Claude Code sessions",
      "title": "env"
    },
    "model": {
      "description": "Override the default AI model",
      "type": "string",
      "title": "model"
    },
    "hooks": {
      "description": "Custom hooks for tool execution",
      "type": "object",
      "properties": {
        "PreToolUse": {
          "description": "Hooks that run before tool calls",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "PreToolUse"
        },
        "PostToolUse": {
          "description": "Hooks that run after tool completion",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "PostToolUse"
        },
        "Notification": {
          "description": "Hooks that run on notifications",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "Notification"
        },
        "UserPromptSubmit": {
          "description": "Hooks that run when user submits a prompt",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "UserPromptSubmit"
        },
        "Stop": {
          "description": "Hooks that run when stopping",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "Stop"
        },
        "SubagentStop": {
          "description": "Hooks that run when subagent stops",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "SubagentStop"
        },
        "PreCompact": {
          "description": "Hooks that run before compacting",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "PreCompact"
        },
        "SessionStart": {
          "description": "Hooks that run at session start",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "SessionStart"
        },
        "SessionEnd": {
          "description": "Hooks that run at session end",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookMatcher"
          },
          "title": "SessionEnd"
        }
      },
      "title": "hooks"
    },
    "apiKeyHelper": {
      "description": "Script path for generating authentication values",
      "type": "string",
      "title": "apiKeyHelper"
    },
    "statusLine": {
      "$ref": "#/definitions/StatusLineConfig",
      "description": "Custom status line configuration",
      "title": "statusLine"
    },
    "outputStyle": {
      "description": "Output style configuration",
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "string"
        }
      ],
      "title": "outputStyle"
    }
  },
  "definitions": {
    "Record<string,string>": {
      "title": "Record<string,string>",
      "type": "object"
    },
    "HookMatcher": {
      "description": "Hook matcher configuration",
      "title": "HookMatcher",
      "type": "object",
      "properties": {
        "matcher": {
          "description": "Tool pattern matcher (optional, case-sensitive)\nEmpty string or \"*\" matches all tools\nUse \"|\" to match multiple tools: \"Edit|Write|MultiEdit\"",
          "pattern": "^(\\*|||(Edit|Bash|Glob|Grep|MultiEdit|NotebookEdit|NotebookRead|Read|Task|TodoWrite|WebFetch|WebSearch|Write)(\\|(Edit|Bash|Glob|Grep|MultiEdit|NotebookEdit|NotebookRead|Read|Task|TodoWrite|WebFetch|WebSearch|Write))*)$",
          "examples": [
            "Edit|MultiEdit|Write",
            "Bash",
            "*",
            ""
          ],
          "type": "string",
          "title": "matcher"
        },
        "hooks": {
          "description": "Array of hooks to execute",
          "type": "array",
          "items": {
            "$ref": "#/definitions/HookCommand"
          },
          "title": "hooks"
        }
      },
      "required": [
        "hooks"
      ]
    },
    "HookCommand": {
      "description": "Hook command configuration",
      "title": "HookCommand",
      "type": "object",
      "properties": {
        "type": {
          "description": "Command type",
          "type": "string",
          "const": "command",
          "title": "type"
        },
        "command": {
          "description": "Command to execute",
          "type": "string",
          "title": "command"
        },
        "timeout": {
          "description": "Timeout in seconds (optional)",
          "type": "number",
          "title": "timeout"
        }
      },
      "required": [
        "command",
        "type"
      ]
    },
    "StatusLineConfig": {
      "description": "Status line command configuration",
      "title": "StatusLineConfig",
      "type": "object",
      "properties": {
        "type": {
          "description": "Status line type",
          "type": "string",
          "const": "command",
          "title": "type"
        },
        "command": {
          "description": "Command or script path to execute for status line",
          "type": "string",
          "title": "command"
        },
        "padding": {
          "description": "Padding for status line display (optional)\nSet to 0 for edge-to-edge display",
          "type": "number",
          "title": "padding"
        }
      },
      "required": [
        "command",
        "type"
      ]
    }
  },
  "examples": [
    {
      "permissions": {
        "allow": [
          "Bash(git diff:*)",
          "Read(src/*)"
        ],
        "deny": [
          "Read(./.env)",
          "WebFetch"
        ],
        "ask": [
          "Write(*)"
        ]
      },
      "env": {
        "NODE_ENV": "development"
      },
      "model": "claude-3-5-sonnet-20241022"
    }
  ]
}

I made https://github.com/[spences10/claude-code-settings-schema](https://github.com/spences10/claude-code-settings-schema) as a npm package you can now npx claude-code-settings-schema to generate the schema