Configuration Intermediate

Claude Code is highly configurable. You can customize its behavior through settings files, project-level CLAUDE.md files, permission controls, model selection, MCP servers, custom slash commands, hooks, and environment variables.

Settings Files

Claude Code stores user-level settings in ~/.claude/settings.json. This file controls global behavior across all projects.

JSON (~/.claude/settings.json)
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(rm -rf)",
      "Bash(sudo *)"
    ]
  },
  "model": "claude-sonnet-4-20250514",
  "theme": "dark"
}

Settings Hierarchy

Claude Code loads settings from multiple locations, with more specific settings overriding general ones:

Priority Location Scope
1 (highest) .claude/settings.json (in project) Project-specific settings
2 ~/.claude/settings.json User-level settings (all projects)
3 Command-line flags Current session only
4 (lowest) Default values Built-in defaults

Project Settings (CLAUDE.md)

The CLAUDE.md file provides project-level context and instructions to Claude Code. It is read automatically at the start of every session when present in the project root.

CLAUDE.md vs settings.json: Use CLAUDE.md for project context, coding conventions, and architectural notes. Use settings.json for tool permissions, model selection, and technical configuration.

CLAUDE.md Locations

Location When It's Read Use For
~/CLAUDE.md Every session (user-level) Personal preferences, global conventions
./CLAUDE.md (project root) When in that project Project architecture, conventions, common commands
./src/CLAUDE.md (subdirectory) When Claude reads files in that directory Module-specific context and patterns

Example CLAUDE.md

Markdown (CLAUDE.md)
# My Project

## Tech Stack
- React 18 with TypeScript
- Express.js backend
- PostgreSQL with Prisma ORM
- Jest for testing

## Conventions
- Use functional components with hooks
- Named exports only (no default exports)
- Use Zod for runtime validation
- All API routes return { data, error } shape
- camelCase for variables, PascalCase for components

## Commands
- `npm run dev` - Start development server (port 3000)
- `npm test` - Run all tests
- `npm run test:watch` - Run tests in watch mode
- `npx prisma migrate dev` - Run database migrations

## Important Notes
- Never modify files in src/generated/ (auto-generated by Prisma)
- The database schema is in prisma/schema.prisma
- Environment variables are in .env.local (never commit this)

Permission Settings

Permissions control which tools Claude Code can use without asking. You can configure granular allow/deny rules for each tool.

JSON (settings.json)
{
  "permissions": {
    "allow": [
      // Always allow read-only tools
      "Read",
      "Glob",
      "Grep",

      // Allow specific safe commands
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",

      // Allow file editing
      "Edit",
      "Write"
    ],
    "deny": [
      // Never allow destructive commands
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Bash(git push --force *)"
    ]
  }
}
Wildcard Patterns: Use * as a wildcard in permission rules. For example, "Bash(git diff *)" allows any git diff command regardless of arguments.

Model Selection

Claude Code supports multiple Claude models. You can set the default model in settings or switch during a session.

Model Best For Speed Cost
claude-sonnet-4-20250514 Most coding tasks. Good balance of speed and quality. Fast Lower
claude-opus-4-20250514 Complex reasoning, architecture decisions, difficult bugs. Slower Higher
Terminal
# Set model at startup
$ claude --model claude-opus-4-20250514

# Change model during a session
Claude > /model claude-opus-4-20250514

# Set default model in settings
# Add to ~/.claude/settings.json:
# "model": "claude-sonnet-4-20250514"

MCP Servers

MCP (Model Context Protocol) servers extend Claude Code's capabilities by providing additional tools. You can connect Claude Code to databases, APIs, browsers, and other external systems through MCP.

JSON (~/.claude/settings.json)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
MCP Server Discovery: Find available MCP servers at github.com/modelcontextprotocol/servers. There are servers for databases, cloud services, browsers, and more.

Custom Slash Commands

You can define your own slash commands to automate repetitive tasks. Custom commands are defined in your project's .claude/ directory.

Markdown (.claude/commands/review-pr.md)
Review the current git diff carefully. For each changed file:

1. Check for logic errors or bugs
2. Verify error handling is comprehensive
3. Look for security issues (SQL injection, XSS, etc.)
4. Check for performance concerns
5. Verify test coverage for new/changed code

Provide a summary with:
- Overall assessment (ready to merge / needs changes)
- List of issues found (if any)
- Suggestions for improvement
Claude Code Session
# Use your custom command
Claude > /review-pr

# Custom commands with arguments (use $ARGUMENTS placeholder)
Claude > /review-pr --focus security
Command Ideas: Create custom commands for common tasks in your workflow:
  • /deploy-check — Run pre-deployment verification checks
  • /new-component — Create a new React component with boilerplate
  • /db-migrate — Create a new database migration
  • /audit-deps — Check for outdated or vulnerable dependencies

Hooks

Hooks let you run custom scripts before or after Claude Code takes certain actions. They are defined in your settings file.

JSON (settings.json)
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to edit a file'"
          }
        ]
      }
    ],
    "postToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "afterMessage": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --quiet"
          }
        ]
      }
    ]
  }
}
Hook Type When It Runs Common Use
preToolUse Before a tool is executed Validation, logging, backup
postToolUse After a tool completes Formatting, linting, notifications
afterMessage After Claude sends a response Running tests, verification checks

Environment Variables

Claude Code reads several environment variables for configuration:

Variable Description Example
ANTHROPIC_API_KEY Your Anthropic API key for authentication sk-ant-api03-...
ANTHROPIC_MODEL Default model to use claude-sonnet-4-20250514
CLAUDE_CODE_USE_BEDROCK Use AWS Bedrock instead of the Anthropic API 1
CLAUDE_CODE_USE_VERTEX Use Google Cloud Vertex AI instead of the Anthropic API 1
HTTPS_PROXY HTTP proxy for API calls http://proxy:8080
CLAUDE_CODE_MAX_TURNS Maximum number of agentic turns per request 50
Terminal
# Set environment variables in your shell profile
$ echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
$ echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.bashrc
$ source ~/.bashrc

Configuration Quick Reference

What Where Format
User settings ~/.claude/settings.json JSON
Project settings .claude/settings.json JSON
Project context CLAUDE.md Markdown
Custom commands .claude/commands/*.md Markdown
MCP servers ~/.claude/settings.json JSON (mcpServers key)
Hooks settings.json JSON (hooks key)
API key Environment variable ANTHROPIC_API_KEY

Try It Yourself

Customize your Claude Code setup:

  1. Create a CLAUDE.md file in your project root with your coding conventions
  2. Create a custom slash command in .claude/commands/ for a task you do frequently
  3. Add a few safe commands to the allow list in your settings
  4. Try switching between Claude models using /model