Claude Code Settings & Configuration

Updated May 2026 · Complete configuration reference

Claude Code has three layers of configuration that stack on top of each other: environment variables (highest priority), settings.json files (project and global), and CLAUDE.md files (instruction context). This page covers all of them.

Configuration Priority Order

settings.json Full Reference

// .claude/settings.json — annotated example
{
  // Model to use (overridable per-session with --model)
  "model": "claude-sonnet-4-6",

  // Pre-approve specific tools to reduce confirmation prompts
  "permissions": {
    "allow": [
      "Read",          // Read files
      "Bash(git *)",   // Any git command
      "Bash(npm *)",   // Any npm command
      "Bash(python *)" // Any python command
    ],
    "deny": [
      "Bash(rm -rf *)" // Never allow recursive delete
    ]
  },

  // Environment variables injected into every Bash command
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  },

  // Hooks — shell commands that fire at lifecycle events
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "echo 'Running: $CLAUDE_TOOL_INPUT'"}]
      }
    ],
    "Stop": [
      {
        "hooks": [{"type": "command", "command": "notify-send 'Claude Code done'"}]
      }
    ]
  },

  // Disable specific features
  "theme": "dark",
  "autoUpdates": false,
  "verbose": false
}

File Locations

# Global settings — applies to all projects
~/.claude/settings.json

# Project settings — committed to git (team-shared)
.claude/settings.json

# Project local settings — NOT committed (add to .gitignore)
.claude/settings.local.json

# CLAUDE.md — instructions for Claude (not config)
CLAUDE.md              # project root (loaded always)
src/CLAUDE.md          # subdirectory (loaded when working in src/)
~/.claude/CLAUDE.md    # global (loaded in every project)

Model Configuration

# In settings.json
{"model": "claude-opus-4-7"}

# Via environment variable
export ANTHROPIC_MODEL=claude-haiku-4-5-20251001

# Per-session override
claude --model claude-sonnet-4-6

Permissions Configuration

Reduce confirmation prompts by pre-approving tools in settings.json. Use specific patterns to grant narrow permissions rather than broad ones:

{
  "permissions": {
    "allow": [
      "Read",              // allow all file reads
      "Write",             // allow all file writes
      "Edit",              // allow all edits
      "Bash(git *)",       // allow any git command
      "Bash(npm test)",    // allow only 'npm test'
      "Bash(npm run *)"    // allow any 'npm run ...' command
    ],
    "deny": [
      "Bash(rm -rf *)",    // never allow recursive delete
      "Bash(git push *)"   // require manual push confirmation
    ]
  }
}

Environment Variables Reference

Hooks Configuration

Hooks run shell commands at lifecycle events. The available events are:

{
  "hooks": {
    // Log every bash command to a file
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo \"$(date -u) $CLAUDE_TOOL_INPUT\" >> ~/.claude-audit.log"
      }]
    }],
    // Desktop notification when Claude stops
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Done\" with title \"Claude Code\"' 2>/dev/null || true"
      }]
    }]
  }
}

CLAUDE.md vs settings.json

Frequently Asked Questions

→ CLAUDE.md Guide — write effective project instructions

→ Hooks — automate pre/post tool actions

← Back to Home