Settings - Claude Code Templates

Settings control how Claude Code behaves in your projects. They define permissions, model preferences, environment variables, hook configurations, and advanced features like status lines and context monitoring.

What Are Settings?

Settings are JSON configuration files that customize Claude Code:

Permissions - What Claude can and cannot do
Environment variables - Configuration values and secrets
Hooks - Event-driven automation
Model preferences - Which Claude model to use
Status lines - Real-time monitoring and feedback
Advanced features - Telemetry, retention, and more

Settings cascade from user → project → local, with later settings overriding earlier ones.

Settings Hierarchy

Claude Code uses three levels of settings:

User Settings
Project Settings
Local Settings

Location: ~/.claude/settings.jsonScope: All projects for the current userUse for:

Personal preferences (editor, model)
Global API keys
User-specific automation

# Install to user settings
npx claude-code-templates@latest --setting use-sonnet
# Choose "User settings" when prompted

Committed: No (personal file)

Location: .claude/settings.jsonScope: Current project, shared with teamUse for:

Team conventions
Project-specific permissions
Shared automation
CI/CD configuration

# Install to project settings
npx claude-code-templates@latest --setting allow-npm-commands
# Choose "Project settings" when prompted

Committed: Yes (shared with team via git)

Location: .claude/settings.local.jsonScope: Current project, personal overridesUse for:

Personal overrides for project settings
Local API keys and secrets
Development-only hooks

# Install to local settings (default)
npx claude-code-templates@latest --setting context-monitor
# Choose "Local settings" when prompted

Committed: No (add to .gitignore)

Local settings override project settings, which override user settings. This allows personal customization without affecting the team.

Settings Structure

Settings files use JSON format:

{
  "permissions": {
    "allow": ["Bash(npm run test)"],
    "deny": ["Bash(rm -rf)"],
    "ask": ["Bash(git push)"]
  },
  "env": {
    "NODE_ENV": "development",
    "API_KEY": "${API_KEY}"
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "npm run format"
      }]
    }]
  },
  "statusLine": {
    "type": "command",
    "command": "python3 .claude/scripts/context-monitor.py"
  },
  "model": "sonnet",
  "telemetry": true
}

Settings Categories

Control what Claude can execute:

allow-npm-commands - Enable npm/yarn operations
read-only-mode - Prevent all file modifications
deny-sensitive-files - Block access to secrets
allow-git-operations - Enable git commands

npx claude-code-templates@latest --setting permissions/allow-npm-commands

Configuration:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(npm start)"
    ]
  }
}

Permission Types:

allow - Always permit these operations
deny - Always block these operations
ask - Prompt user before executing

Choose which Claude model to use:

use-sonnet - Claude 3.5 Sonnet (balanced, default)
use-opus - Claude 3 Opus (most capable)
use-haiku - Claude 3.5 Haiku (fastest, cheapest)

npx claude-code-templates@latest --setting model/use-sonnet

Configuration:

{
  "model": "sonnet"
}

Model Comparison:

Model	Speed	Cost	Best For
Haiku	Fastest	Lowest	Simple tasks, formatting
Sonnet	Balanced	Medium	Most development work
Opus	Slowest	Highest	Complex analysis, architecture

Real-time monitoring and feedback:

context-monitor - Track context usage with progress bars
token-counter - Display token consumption
session-tracker - Monitor session duration and cost

npx claude-code-templates@latest --setting statusline/context-monitor

Configuration:

{
  "statusLine": {
    "type": "command",
    "command": "python3 .claude/scripts/context-monitor.py"
  }
}

Features:

Visual progress bars
Color-coded alerts (green/yellow/red)
Session analytics (cost, duration, lines changed)
Auto-compact warnings

Set environment variables:

env-development - Development environment vars
env-production - Production configuration
api-keys - External service credentials

npx claude-code-templates@latest --setting environment/env-development

Configuration:

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true",
    "API_URL": "http://localhost:3000",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

Never hardcode secrets. Use ${VAR} syntax to reference shell environment variables.

Control usage tracking:

enable-telemetry - Send anonymous usage data
disable-telemetry - Opt out of tracking

npx claude-code-templates@latest --setting telemetry/disable-telemetry

Configuration:

{
  "telemetry": false
}

Telemetry helps improve Claude Code but is optional.

Control conversation history:

retention-7-days - Keep 7 days of history
retention-30-days - Keep 30 days of history
retention-90-days - Keep 90 days of history

npx claude-code-templates@latest --setting cleanup/retention-7-days

Configuration:

{
  "retention": {
    "days": 7,
    "autoCleanup": true
  }
}

Automatically removes old conversations to save disk space.

Real-World Examples

Example 1: Allow NPM Commands

File: Settings configuration

{
  "description": "Allow common npm development commands (lint, test, build, start)",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(npm start)"
    ]
  }
}

Behavior:

Claude can run npm run lint, npm run test:unit, npm run build, npm start
User is not prompted for permission
Wildcard * matches any suffix (e.g., test:unit, test:integration)

Example 2: Context Monitor Statusline

File: Settings configuration

{
  "description": "Real-time Claude Code context usage monitor with visual progress bars",
  "statusLine": {
    "type": "command",
    "command": "python3 .claude/scripts/context-monitor.py"
  }
}

Supporting Script: .claude/scripts/context-monitor.py The CLI automatically downloads the Python script when installing this setting. Display Output:

Context: [=========>    ] 67% (134k/200k tokens)
Session: 12m 34s | Cost: $0.45 | 127 lines changed

Example 3: Read-Only Mode

File: Settings configuration

{
  "permissions": {
    "deny": [
      "Write(*)",
      "Edit(*)",
      "Bash(*)"
    ],
    "allow": [
      "Read(*)",
      "Glob(*)",
      "Grep(*)"
    ]
  }
}

Behavior:

Claude can only read files and search
All write operations are blocked
No shell commands allowed
Useful for code review and analysis

Installing Settings

Single Setting

npx claude-code-templates@latest --setting allow-npm-commands

You’ll be prompted to choose installation location:

User settings (~/.claude/settings.json)
Project settings (.claude/settings.json)
Local settings (.claude/settings.local.json)
Enterprise managed settings (requires admin)

Multiple Settings

npx claude-code-templates@latest \
  --setting use-sonnet \
  --setting allow-npm-commands \
  --setting context-monitor

Batch Installation to Specific Location

Skip prompts by using shared locations:

# Install all to local settings
npx claude-code-templates@latest \
  --setting use-sonnet \
  --setting context-monitor \
  --location local

Settings merge with existing configuration. Conflicting settings prompt for confirmation.

Permission Patterns

Use wildcards and patterns for flexible permissions:

Wildcard Matching

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)"  // Matches test:unit, test:integration, etc.
    ],
    "deny": [
      "Write(*.env*)"         // Blocks .env, .env.local, .env.production
    ]
  }
}

Tool-Level Permissions

{
  "permissions": {
    "allow": [
      "Read(*)",     // Allow all file reads
      "Glob(*)",     // Allow all file searches
      "Grep(*)"      // Allow all content searches
    ],
    "deny": [
      "Bash(*)"      // Block all shell commands
    ]
  }
}

Path-Based Permissions

{
  "permissions": {
    "allow": [
      "Edit(src/*)",          // Allow edits in src/
      "Write(tests/*)",       // Allow creating test files
      "Bash(npm run test)"    // Allow test execution
    ],
    "deny": [
      "Edit(node_modules/*)", // Prevent node_modules edits
      "Write(.env*)"          // Prevent .env file creation
    ]
  }
}

Environment Variable Best Practices

Use Variable Substitution

DON’T hardcode secrets:

{
  "env": {
    "API_KEY": "sk-1234567890"  // ❌ Exposed in git
  }
}

DO reference environment variables:

{
  "env": {
    "API_KEY": "${API_KEY}"  // ✅ Reads from shell
  }
}

Use .env Files

Create .env file (add to .gitignore):

API_KEY=sk-1234567890
DATABASE_URL=postgresql://localhost/db

Reference in settings:

{
  "env": {
    "API_KEY": "${API_KEY}",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

Load with dotenv:

export $(cat .env | xargs)

Conflict Resolution

When installing settings that conflict with existing configuration:

Conflict Detection - CLI identifies conflicting values
User Prompt - Shows current vs new values
User Choice - Overwrite or skip
Merge Strategy - Arrays merge, objects overwrite

Example conflict prompt:

⚠️ Conflicts detected:
  • Setting "model" (current: "opus", new: "sonnet")
  • Environment variable "NODE_ENV" (current: "production", new: "development")

Do you want to overwrite the existing configuration? (y/N)

Settings Merging

Array Merging

Permission arrays merge uniquely: Existing:

{
  "permissions": {
    "allow": ["Bash(npm test)"]
  }
}

New:

{
  "permissions": {
    "allow": ["Bash(npm build)"]
  }
}

Result:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm build)"
    ]
  }
}

Object Overwriting

Top-level settings overwrite: Existing:

{
  "model": "opus"
}

New:

{
  "model": "sonnet"
}

Result:

{
  "model": "sonnet"  // Overwrites
}

Enterprise Settings

Enterprise managed settings enforce organization-wide policies: Locations:

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux: /etc/claude-code/managed-settings.json
Windows: C:\ProgramData\ClaudeCode\managed-settings.json

Requires: Administrator privileges Use cases:

Security policies
Compliance requirements
Organization standards

Enterprise settings override all other settings and cannot be modified by users.

Settings Best Practices

1. Principle of Least Privilege

Only grant necessary permissions:

{
  "permissions": {
    "allow": [
      "Bash(npm run test)"  // Specific command
    ]
  }
}

Not:

{
  "permissions": {
    "allow": [
      "Bash(*)"  // Too permissive
    ]
  }
}

2. Separate Concerns

User settings: Personal preferences
Project settings: Team conventions
Local settings: Secrets and overrides

3. Document Settings

Add comments (in description field during installation):

{
  "permissions": {
    "allow": ["Bash(npm run test)"]  // Required for CI/CD pipeline
  }
}

4. Version Control

Commit:

.claude/settings.json (project settings)

Don’t commit:

.claude/settings.local.json (personal overrides)
~/.claude/settings.json (user settings)

Add to .gitignore:

.claude/settings.local.json

Viewing Current Settings

Check active settings:

# View project settings
cat .claude/settings.json

# View local settings
cat .claude/settings.local.json

# View user settings
cat ~/.claude/settings.json

Settings cascade: user → project → local.

Removing Settings

Manually edit settings files to remove configurations:

# Edit project settings
code .claude/settings.json

# Edit local settings
code .claude/settings.local.json

Remove unwanted sections or reset to {}.

Next Steps

Browse Settings

Explore 60+ available settings

Configuration

Configure Claude Code settings

Hooks

Automate with event-driven triggers

Templates

Complete project configurations

Get Started

Core Concepts

Guides

Tools

Advanced

​What Are Settings?

​Settings Hierarchy

​Settings Structure

​Settings Categories

​Real-World Examples

​Example 1: Allow NPM Commands

​Example 2: Context Monitor Statusline

​Example 3: Read-Only Mode

​Installing Settings

​Single Setting

​Multiple Settings

​Batch Installation to Specific Location

​Permission Patterns

​Wildcard Matching

​Tool-Level Permissions

​Path-Based Permissions

​Environment Variable Best Practices

​Use Variable Substitution

​Use .env Files

​Conflict Resolution

​Settings Merging

​Array Merging

​Object Overwriting

​Enterprise Settings

​Settings Best Practices

​1. Principle of Least Privilege

​2. Separate Concerns

​3. Document Settings

​4. Version Control

​Viewing Current Settings

​Removing Settings

​Next Steps

Browse Settings

Configuration

Hooks

Templates

Build docs developers (and LLMs) love

What Are Settings?

Settings Hierarchy

Settings Structure

Settings Categories

Real-World Examples

Example 1: Allow NPM Commands

Example 2: Context Monitor Statusline

Example 3: Read-Only Mode

Installing Settings

Single Setting

Multiple Settings

Batch Installation to Specific Location

Permission Patterns

Wildcard Matching

Tool-Level Permissions

Path-Based Permissions

Environment Variable Best Practices

Use Variable Substitution

Use .env Files

Conflict Resolution

Settings Merging

Array Merging

Object Overwriting

Enterprise Settings

Settings Best Practices

1. Principle of Least Privilege

2. Separate Concerns

3. Document Settings

4. Version Control

Viewing Current Settings

Removing Settings

Next Steps