8.1 Settings Overview

Course: Claude Code - Power User Section: Configuration Video Length: 3-4 minutes Presenter: Daniel Treasure

Opening Hook

Claude Code has four distinct settings layers—and they don't fight each other, they work together. Understanding this hierarchy is the key to controlling how Claude Code behaves on every level.

Key Talking Points

1. The Settings Hierarchy

Four layers with clear precedence (highest to lowest)
Managed (system-wide) → CLI arguments → Local (project) → User (home) → Project (workspace)
Each layer can override the one below it
No conflicts—the stack is predictable

What to say: "Think of this like CSS cascading—more specific settings win. You set broad rules at the user level, then narrow them down for specific projects or commands."

What to show on screen: Open terminal and show file paths: - Managed: /Library/Application Support/ClaudeCode/ (macOS) or /etc/claude-code/ (Linux) - Local: .claude/settings.local.json (repo root) - Project: .claude/settings.json (repo root) - User: ~/.claude/settings.json (home directory)

2. User-Level Settings

Personal preferences, model selection, default behaviors
Lives in ~/.claude/settings.json
Applied across all projects unless overridden
Examples: preferred model, language, auto-updates, thinking toggle

What to say: "Your user settings are your baseline. These are the defaults you want for every project you work on."

What to show on screen: cat ~/.claude/settings.json (with sensitive data redacted)

3. Project-Level Settings

Coding standards, tool rules, specific behaviors for a workspace
Lives in .claude/settings.json in repo root
Shared with team (check into version control)
Overrides user settings for that project

What to say: "Project settings are how teams align. Different repos can have different rules—strict TypeScript requirements in one, relaxed in another."

What to show on screen: Show a .claude/settings.json from a sample project with comments explaining each field

4. Local Settings (Machine-Specific)

.claude/settings.local.json for sensitive or machine-specific config
NOT checked into git (should be in .gitignore)
Overrides project and user settings
Use for API keys, local paths, development-only toggles

What to say: "Local settings are your escape hatch. Keep them out of version control and use them for anything that shouldn't be shared."

What to show on screen: Show .gitignore entry for .claude/settings.local.json, then show example local file with API key placeholders

5. Managed / Enterprise Settings

System-wide controls (admin, security policies)
Enforced across all users on the machine
Cannot be overridden by user or project
For organizations and controlled environments

What to say: "If your organization has managed Claude Code, those policies sit at the top. You can't override them, and that's by design."

What to show on screen: Mention the paths but don't dive deep (most viewers won't interact with these)

6. Key Settings Fields to Know

model: default model (sonnet, opus, haiku)
language: preferred language (en, es, fr, etc.)
autoUpdatesChannel: stable or beta
alwaysThinkingEnabled: whether Claude thinks by default
outputStyle: verbose or concise
permissions: allow/deny/ask rules (covered in 8.2)
sandbox: filesystem and network isolation (covered in 8.5)
hooks: custom commands or scripts
env: environment variables specific to this layer
attribution: credit instructions for generated code

What to say: "You don't need to memorize all these. But knowing they exist means you can fine-tune exactly what you need."

What to show on screen: Scroll through a well-commented example settings.json, highlighting 4-5 key fields

Demo Plan

Show the hierarchy visually (45 sec)
Open terminal, navigate to home directory
cat ~/.claude/settings.json to show user settings
Navigate to a sample project, show .claude/settings.json
Mention .claude/settings.local.json (don't open if it contains secrets)
Explain cascading precedence (1 min)
Walk through a scenario: "If I set model=sonnet in user settings, but haiku in project settings, which wins?"
Answer: project always wins
Show how to check effective settings with claude code --show-config (or equivalent)
Talk through a real project example (1 min 15 sec)
Open a sample project's settings
Point out language, permissions, and model choices
Explain why the team made these choices
Preview next video (30 sec)
"Next, we'll talk permissions—how to control what Claude Code can actually do."

Code Examples & Commands

View user settings:

cat ~/.claude/settings.json

View project settings:

cat .claude/settings.json

Check local overrides:

cat .claude/settings.local.json  # NOT in version control

Example user-level settings.json:

{
  "model": "claude-3-5-sonnet-20241022",
  "language": "en",
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "outputStyle": "verbose",
  "permissions": {
    "allow": ["bash(npm run *)", "read(./)"],
    "deny": ["bash(rm -rf *)", "bash(git push *)"]
  }
}

Example project-level settings.json:

{
  "model": "claude-3-5-sonnet-20241022",
  "language": "en",
  "permissions": {
    "allow": ["bash(npm test)", "edit(src/**/*.ts)"],
    "deny": ["bash(docker *)"],
    "ask": ["bash(npm install *)", "bash(git commit *)"]
  },
  "attribution": "Generated code must include attribution comment"
}

Gotchas & Tips

Settings are JSON: Invalid JSON breaks things silently. Use a linter or editor with JSON validation.
Permissions are inherited, not replaced: If user settings allow npm, project settings that add more rules don't block npm—they add on top.
.local files are your secret: Remember to .gitignore them and add them to team docs.
Managed settings override everything: If your org uses managed settings, you can't change them at the user or project level. This is a feature, not a bug.
Changes take effect immediately: Most settings apply on the next Claude Code invocation. Some (like model) might need a new session.

Lead-out

Settings are how you customize Claude Code to match your workflow. The next four videos go deep into permissions, model selection, environment variables, and sandbox mode—the specific levers you'll pull most often.

Reference URLs

Claude Code documentation: https://claude.ai/docs/claude-code
Settings JSON schema (if available): [check docs]
Common settings patterns: [team wiki or internal docs]

Prep Reading

Review the Claude Code settings documentation
Understand JSON syntax (basic)
Know the difference between user, project, and local config
Familiarize yourself with your own ~/.claude/settings.json (if it exists)

Notes for Daniel: This is the conceptual foundation for the whole section. Spend time on the hierarchy—it's the mental model that makes everything else click. Visual diagrams (flowcharts, file trees) will help here more than code. Keep the tone reassuring: "This looks complicated, but it's actually well-designed."

Quick Reference