Mastering Project Settings

Introduction

Welcome back to Customizing Claude Code for Your Projects! In the first two units, we established how to guide Claude's behavior through project instructions (CLAUDE.md) and how to control which files it sees (.claudeignore). Now, in this third unit, we'll explore a more granular level of customization: settings files . While CLAUDE.md defines what to do and .claudeignore defines what to see, settings files control how Claude operates, from which model it uses to how it handles permissions. We'll learn to configure behavior at multiple levels, creating both team-wide standards and personal preferences that shape every interaction with Claude .

Configuration as Control

Before diving into specific files, let's understand why settings files matter. Every time Claude starts, it makes decisions: which model to use (Sonnet, Haiku, or Opus), how to handle permissions (ask every time, auto-approve certain tools, or plan without executing), and what operations to allow or deny. Without configuration, these decisions follow default behavior, which might not match our workflow. Settings files give us declarative control over these choices. Instead of manually switching models or repeatedly approving the same permissions, we define preferences once and Claude respects them automatically. More importantly, settings exist at different levels: some apply globally across all projects, others define team standards for a specific repository, and still others represent personal preferences that override everything else. This layered approach lets us balance consistency with flexibility.

The Three Configuration Layers

Claude recognizes three distinct levels of configuration, each stored in a different location. The user level lives in ~/.claude/settings.json and defines your personal defaults across all projects. When you prefer Sonnet as your general-purpose model or always want to review bash commands, those preferences belong here. The project level lives in .claude/settings.json within the project directory. This file typically gets committed to version control, establishing shared standards for everyone working on the codebase. If a data analysis project should default to Haiku for cost efficiency or block access to sensitive files, those rules belong in project settings. The local level lives in .claude/settings.local.json, also in the project directory but typically excluded from version control (like .env files). This is where you override project settings with personal preferences. Perhaps your team uses normal permission mode, but you prefer plan mode for careful review. Local settings let you customize without affecting others.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Configuring Project Defaults

Now, let's say we're working on a data analysis project where we want different behavior. We'll configure project-specific settings:

text

> Create a new file at .claude/settings.json. Configure it to: Set the AI model to "haiku", 
  set the default permission mode to "default", and add a deny array inside the permissions block 
  that blocks access to .env files using these patterns: "Read(./.env)" and "Read(./.env.*)"

● Bash(mkdir -p .claude)
  ⎿ (No content)

● Write(.claude/settings.json)
  ⎿ Wrote 11 lines to .claude/settings.json
    {
      "model": "haiku",
      "permissions": {
        "defaultMode": "default",
        "deny": [
          "Read(./.env)",
          "Read(./.env.*)"
        ]
      }
    }

● Done! I've created the .claude/settings.json file with your requested configuration:
  - Model: Set to "haiku" for faster, lighter processing
  - Permission mode: Set to "default" for the standard safety setting
  - Deny patterns: Blocks Read access to .env and .env.* files

> Create a new file at .claude/settings.json. Configure it to: Set the AI model to "haiku", 
  set the default permission mode to "default", and add a deny array inside the permissions block 
  that blocks access to .env files using these patterns: "Read(./.env)" and "Read(./.env.*)"

● Bash(mkdir -p .claude)
  ⎿ (No content)

● Write(.claude/settings.json)
  ⎿ Wrote 11 lines to .claude/settings.json
    {
      "model": "haiku",
      "permissions": {
        "defaultMode": "default",
        "deny": [
          "Read(./.env)",
          "Read(./.env.*)"
        ]
      }
    }

● Done! I've created the .claude/settings.json file with your requested configuration:
  - Model: Set to "haiku" for faster, lighter processing
  - Permission mode: Set to "default" for the standard safety setting
  - Deny patterns: Blocks Read access to .env and .env.* files

Claude creates .claude/settings.json in the project directory with several important configurations. The "model": "haiku" setting specifies Haiku as the preferred model for this project, choosing the faster and more cost-effective option for routine analysis tasks.

The "permissions" block contains the permission-related settings. Within it, "defaultMode": "default" ensures Claude will request approval before executing operations, maintaining safety controls. The "deny" array contains patterns that block access to sensitive files:

"Read(./.env)" prevents reading the environment file in the project root.
"Read(./.env.*)" blocks variants like .env.local or .env.production.

These settings establish project-wide defaults that apply to anyone working in this repository. Note that model changes typically take effect when starting a new session rather than immediately in the current session.

Introduction

Configuration as Control

The Three Configuration Layers

Join the 1M+ learners on CodeSignal

Viewing Current Configuration

Configuring Project Defaults

Adding Personal Overrides

Verifying Active Configuration

Understanding Settings Precedence

Allow and Deny Lists

Common Configuration Patterns

Managing Settings Over Time

Conclusion and Next Steps