ktg-plugin-marketplace/plugins/config-audit/skills/config-hierarchy/references/settings-json-schema.md

settings.json Schema Reference

File Locations

Location	Precedence	Purpose
~/.claude/settings.json	Lowest	User defaults
.claude/settings.json	Medium	Project shared
.claude/settings.local.json	High	Project local
CLI arguments	Highest	Session only

Schema

{
  // Default model for the project
  "model": "sonnet",

  // Permission rules
  "permissions": {
    // Tools allowed without prompting
    "allow": [
      "Read",
      "Write",
      "Bash(npm*)",
      "Bash(git*)"
    ],
    // Tools that always require approval
    "deny": [
      "Bash(rm -rf*)"
    ]
  },

  // Environment variables to set
  "env": {
    "NODE_ENV": "development"
  },

  // Hooks configuration
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  },

  // MCP server configuration (can also be in .mcp.json)
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "env": {}
    }
  },

  // Custom agents path
  "agents": "./agents",

  // Plugins to load
  "plugins": [
    "~/plugins/my-plugin"
  ]
}

Key Settings

model

Default model for this project/user:

{
  "model": "sonnet"  // or "opus", "haiku"
}

permissions

Control tool access:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm *)",
      "Bash(git *)",
      "Task"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Patterns support wildcards:

• * matches any characters
• Bash(npm*) matches npm install, npm test, etc.

env

Environment variables:

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

hooks

Event-driven automation:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'About to run bash'"
      }
    ]
  }
}

Merging Behavior

When multiple settings files exist:

• Objects are merged recursively
• Arrays are replaced, not merged
• Higher precedence wins for conflicts