Lesson 6: Configuration and Settings

Learning Objectives

After completing this lesson, you will be able to:

Understand the five settings scopes
Create and manage configuration files
Configure common settings effectively
Use environment variables
Set up CLAUDE.md for project context
Use the /config interactive setup

Prerequisites

Completed Lessons 1-5 - Core operations and skills
Text editor - For editing configuration files
Basic JSON knowledge - Configuration files use JSON format

Estimated Time: 20 minutes

Settings Scopes

Claude Code supports multiple configuration scopes, allowing you to customize behavior at different levels.

The Five Scopes (Priority Order)

Settings are merged with this priority (higher priority overrides lower):

1. Managed (Lowest Priority)
         │
2. CLI Flags
         │
3. User
         │
4. Local
         │
5. Project (Highest Priority)

1. Managed Settings

Location: Installation directory Purpose: Default settings Editable: No (managed by Claude Code) Contains: Base configuration that works out of the box

Example: Default model selection, basic permissions

2. CLI Flags

Purpose: Override settings for a single session Precedence: Overrides managed and user settings Usage: Command-line arguments

Examples:

claude --model claude-opus-4-5
claude --mode accept-edits
claude --max-tokens 100000

3. User Settings

Location:

Linux/macOS: ~/.config/claude-code/settings.json
Windows: %APPDATA%\claude-code\settings.json

Purpose: Personal preferences Applies to: All Claude Code sessions (unless overridden) Editable: Yes

Example use cases:

Preferred model
Default permission mode
Personal API keys (if needed)

4. Local Settings

Location: ./.claude/settings.json Purpose: Repository-specific settings Applies to: Sessions started in this directory Git-tracked: Yes (usually)

Example use cases:

Team-shared project configuration
Project-specific tool preferences
Team permission defaults

5. Project Settings

Location: ./.claude-code/settings.json Purpose: Current project configuration Applies to: Only this project Highest priority: Overrides all other scopes

Example use cases:

Experiment-specific settings
Temporary configuration
Override team settings locally

Creating Settings Files

Method 1: Using `/config` (Recommended)

The easiest way to create configuration files.

Interactive setup:

You> /config

Claude will guide you through:

Creating the appropriate settings file
Setting common options
Explaining each setting

Example flow:

You> /config

Claude: I'll help you configure Claude Code.

Which scope do you want to configure?
1. User (applies to all projects)
2. Local (applies to this repository)
3. Project (applies to current project)

Choose a number [1-3]: 2

Claude: Creating .claude/settings.json...

What permission mode do you prefer?
[1] Default (ask for everything)
[2] Accept Edits (auto-approve edits)
[3] Don't Ask (auto-approve most operations)

Choose [1-3]: 1

Claude: Configuration saved!

Method 2: Manual Creation

Create the file manually with a text editor.

User settings example:

mkdir -p ~/.config/claude-code
nano ~/.config/claude-code/settings.json

Local settings example:

mkdir -p .claude
nano .claude/settings.json

Basic Settings Template

{
  "model": "claude-sonnet-4-5",
  "permissionMode": "default",
  "maxTokens": 200000,
  "temperature": 0.7,
  "permissions": {
    "allowedOperations": [],
    "deniedOperations": []
  },
  "mcpServers": {}
}

Common Settings to Configure

Model Selection

Choose which Claude model to use.

Available models:

claude-opus-4-5 - Most capable, most expensive
claude-sonnet-4-5 - Balanced performance and cost (default)
claude-haiku-4-5 - Fastest, least expensive

Configuration:

{
  "model": "claude-sonnet-4-5"
}

When to use each:

Opus: Complex reasoning, architecture, critical features
Sonnet: Most development tasks (recommended default)
Haiku: Quick questions, simple tasks, cost-sensitive work

Permission Mode

Set default permission behavior.

Configuration:

{
  "permissionMode": "default"
}

Options:

default - Ask for everything (safe for beginners)
accept-edits - Auto-approve edits
dont-ask - Auto-approve most operations
bypass - No prompts (use with caution)

Token Limits

Control maximum context size.

Configuration:

{
  "maxTokens": 200000
}

Considerations:

Higher limits = more context, higher cost
Lower limits = faster responses, less cost
Default is usually optimal

Temperature

Control response randomness (creativity).

Configuration:

{
  "temperature": 0.7
}

Scale: 0.0 - 1.0

0.0 - 0.3: Deterministic, focused (good for code generation)
0.4 - 0.7: Balanced (recommended)
0.8 - 1.0: Creative, varied (good for brainstorming)

MCP Servers

Configure MCP integrations (covered in Lesson 7).

Configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"]
    }
  }
}

Language Setting (NEW in 2.1.x!)

Configure Claude's response language.

Configuration:

{
  "language": "japanese"
}

Supported languages: Any language Claude understands (Spanish, French, German, Japanese, Chinese, etc.)

Use cases:

Non-English development teams
Localized responses
Multi-language documentation

Wildcard Permissions (NEW in 2.1.x!)

Use wildcards for flexible permission rules.

Configuration:

{
  "permissions": {
    "allowedOperations": [
      "Bash(*)",           // All bash commands
      "Bash(npm *)",       // All npm commands
      "Bash(git *)",       // All git commands
      "Bash(* test)",      // Commands ending with "test"
      "Read(*.md)",        // All markdown files
      "Edit(src/*)"        // All files in src/
    ]
  }
}

For comprehensive wildcard patterns, see Lesson 20: 2.1.x Advanced Features.

Agent Teams Configuration (NEW in 2.1.33!)

Configure agent teams for split-pane collaboration.

teammateMode setting:

{
  "teammateMode": "tmux"  // or "wezterm", "iterm2", "in-process"
}

agentTeams configuration:

{
  "agentTeams": {
    "fullstack": {
      "name": "Full Stack Team",
      "teammates": [
        {
          "name": "backend",
          "agentType": "general-purpose",
          "model": "claude-sonnet-4-5",
          "systemPrompt": "You are a backend developer."
        },
        {
          "name": "frontend",
          "agentType": "general-purpose",
          "model": "claude-sonnet-4-5",
          "systemPrompt": "You are a frontend developer."
        }
      ]
    }
  }
}

For complete agent teams guide, see Lesson 18: Agent Teams & Teammates.

Environment Variables

Environment variables provide another way to configure Claude Code.

Common Environment Variables

API Key:

export ANTHROPIC_API_KEY="your-api-key-here"

Model Selection:

export CLAUDE_MODEL="claude-sonnet-4-5"

Configuration Directory:

export CLAUDE_CONFIG_DIR="/custom/path"

Permission Mode:

export CLAUDE_PERMISSION_MODE="default"

Setting Environment Variables

Temporary (current session only):

export CLAUDE_MODEL="claude-opus-4-5"
claude

Permanent (add to shell profile):

~/.bashrc or ~/.zshrc:

# Claude Code configuration
export ANTHROPIC_API_KEY="your-key"
export CLAUDE_MODEL="claude-sonnet-4-5"
export CLAUDE_PERMISSION_MODE="accept-edits"

Then reload:

source ~/.bashrc  # or source ~/.zshrc

Priority: Environment Variables vs. Settings Files

Environment variables override settings files.

Priority order:

Environment variables (highest)
Project settings
Local settings
User settings
Managed settings (lowest)

CLAUDE.md for Project Context

CLAUDE.md provides project-specific context that Claude uses across sessions.

What to Include in CLAUDE.md

Project Overview:

# Project Name

Brief description of the project.

Architecture:

## Architecture

- Frontend: React with TypeScript
- Backend: FastAPI (Python)
- Database: PostgreSQL

Conventions:

## Code Conventions

- Use TypeScript strict mode
- Follow PEP 8 for Python code
- Write tests for all new features

Important Files:

## Important Files

- `src/api/` - API endpoints
- `src/utils/` - Shared utilities
- `tests/` - Test files

Development Workflow:

## Development Workflow

Create feature branch
Make changes
Run tests: `npm test`
Commit with /commit

Creating CLAUDE.md

Method 1: Use /memory skill

You> /memory

Method 2: Create manually

nano CLAUDE.md

Example CLAUDE.md

# E-Commerce Platform

Multi-tenant e-commerce platform with inventory management and payment processing.

## Tech Stack

- **Frontend:** Next.js 14, TypeScript, Tailwind CSS
- **Backend:** Node.js, Express, PostgreSQL
- **Auth:** JWT tokens, bcrypt
- **Payments:** Stripe API

## Project Structure

src/ ├── api/ # API routes and controllers ├── models/ # Database models ├── services/ # Business logic ├── utils/ # Helper functions └── middleware/ # Express middleware

## Code Conventions

- Use async/await for async operations
- Handle errors with try-catch
- Log important operations
- Write JSDoc comments for functions
- Follow ESLint rules

## Important Notes

- Never hardcode API keys (use environment variables)
- All database queries must use parameterized statements
- Always validate user input
- Test payment flows in Stripe test mode

## Development Commands

```bash
npm run dev      # Start development server
npm run test     # Run tests
npm run build    # Build for production
npm run lint     # Check code quality

Common Tasks

Adding a new API endpoint: Create in src/api/, register in src/app.js
Database changes: Create migration in migrations/
Frontend components: Add to src/components/

### Benefits of CLAUDE.md

Claude uses this context to:
- Understand your project structure
- Follow your coding conventions
- Know important files and locations
- Suggest appropriate solutions
- Generate consistent code

---

## Practical Example: Setting Up Project Configuration

Let's configure a real project.

### Step 1: Navigate to Project

```bash
cd ~/claude-test/hello-world

Step 2: Create Local Settings

mkdir -p .claude

Create .claude/settings.json:

{
  "model": "claude-sonnet-4-5",
  "permissionMode": "default",
  "temperature": 0.5,
  "permissions": {
    "allowedPatterns": [
      {"pattern": "^hello.py$", "operation": "Read"}
    ]
  }
}

This configures:

Use Sonnet model
Ask for permissions (safe)
Lower temperature (more deterministic)
Auto-allow reading hello.py

Step 3: Create CLAUDE.md

Create CLAUDE.md:

# Hello World Project

A simple project for learning Claude Code basics.

## Purpose

This is a learning project to practice:
- Basic file operations
- Understanding permissions
- Using skills
- Configuration

## Files

- `hello.py` - Main greeting script

## Goals

- Keep it simple
- Focus on learning
- Experiment freely

Step 4: Test Configuration

claude

You> What is the current configuration?

Claude: I can see from your settings:
- Model: claude-sonnet-4-5
- Permission mode: default
- Temperature: 0.5
- Allowed to read hello.py without asking

Step 5: Verify Context

You> What is this project about?

Claude: This is a Hello World learning project for practicing
Claude Code basics including file operations, permissions,
and skills.

Claude used the CLAUDE.md context!

✅ Check Your Understanding

Which settings scope has the highest priority?
- Managed
- User
- Local
- Project
What command helps you create configuration files interactively?
- /settings
- /config
- /setup
- /configure
Where are user settings stored on Linux/macOS?
- ~/claude/settings.json
- ~/.config/claude-code/settings.json
- ~/.claude/settings.json
- /etc/claude/settings.json
True or False: Environment variables override settings files.
- True
- False
What is CLAUDE.md used for?
- Storing API keys
- Project-specific context for Claude
- Listing all files in the project
- Configuring MCP servers

Answers: 1-d, 2-b, 3-b, 4-True, 5-b

Summary

In this lesson, you learned:

Five settings scopes - Managed, CLI, User, Local, Project
Creating settings - Use /config or create files manually
Common settings - Model, permissions, tokens, temperature
Environment variables - Override configuration with env vars
CLAUDE.md - Provide project context to Claude
Configuration priority - Understand merge order

Next Steps

In Lesson 7: MCP Integrations, you'll learn:

What MCP is and why it matters
Types of MCP servers
Adding and configuring MCP servers
Using MCP tools in conversations

Learning Objectives​

Prerequisites​

Settings Scopes​

The Five Scopes (Priority Order)​

1. Managed Settings​

2. CLI Flags​

3. User Settings​

4. Local Settings​

5. Project Settings​

Creating Settings Files​

Method 1: Using /config (Recommended)​

Method 2: Manual Creation​

Basic Settings Template​

Common Settings to Configure​

Model Selection​

Permission Mode​

Token Limits​

Temperature​

MCP Servers​

Language Setting (NEW in 2.1.x!)​

Wildcard Permissions (NEW in 2.1.x!)​

Agent Teams Configuration (NEW in 2.1.33!)​

Environment Variables​

Common Environment Variables​

Setting Environment Variables​

Priority: Environment Variables vs. Settings Files​

CLAUDE.md for Project Context​

What to Include in CLAUDE.md​

Creating CLAUDE.md​

Example CLAUDE.md​

Common Tasks​

Step 2: Create Local Settings​

Step 3: Create CLAUDE.md​

Step 4: Test Configuration​

Step 5: Verify Context​

✅ Check Your Understanding​

Summary​

Next Steps​

Further Reading​

Learning Objectives

Prerequisites

Settings Scopes

The Five Scopes (Priority Order)

1. Managed Settings

2. CLI Flags

3. User Settings

4. Local Settings

5. Project Settings

Creating Settings Files

Method 1: Using `/config` (Recommended)

Method 2: Manual Creation

Basic Settings Template

Common Settings to Configure

Model Selection

Permission Mode

Token Limits

Temperature

MCP Servers

Language Setting (NEW in 2.1.x!)

Wildcard Permissions (NEW in 2.1.x!)

Agent Teams Configuration (NEW in 2.1.33!)

Environment Variables

Common Environment Variables

Setting Environment Variables

Priority: Environment Variables vs. Settings Files

CLAUDE.md for Project Context

What to Include in CLAUDE.md

Creating CLAUDE.md

Example CLAUDE.md

Common Tasks

Step 2: Create Local Settings

Step 3: Create CLAUDE.md

Step 4: Test Configuration

Step 5: Verify Context

✅ Check Your Understanding

Summary

Next Steps

Further Reading