Claude Code Configuration

Claude Code’s behavior is controlled by a layered configuration system: settings.json files at project and global levels, CLAUDE.md files for project-specific instructions, environment variables for runtime control, MCP server definitions for tool integrations, and permission rules for security. This page maps every configuration surface and links to detailed guides.

Configuration Hierarchy

Claude Code reads configuration from multiple sources, with specific precedence rules. Understanding the hierarchy prevents conflicts and unexpected behavior.

Precedence order (highest to lowest):

  1. Command-line flags (--model, --dangerously-skip-permissions)
  2. Environment variables (ANTHROPIC_API_KEY, CLAUDE_MODEL)
  3. Project settings (.claude/settings.json)
  4. User settings (~/.claude/settings.json)
  5. CLAUDE.md instructions
  6. Default values

settings.json Configuration

The .claude/settings.json file controls Claude Code’s operational behavior: which tools are allowed, what permissions are granted, and how the agent interacts with your system.

Project Settings

Project settings live in .claude/settings.json within your repository. They are committed to version control and shared across the team.

Global Settings

Global settings live in ~/.claude/settings.json and apply to all projects. Use these for personal preferences that should not vary by project.

CLAUDE.md Configuration

Your CLAUDE.md file is not just documentation – it is active configuration that shapes how Claude Code interprets and modifies your codebase.

Core Guides

Generate yours: The CLAUDE.md Generator creates a production-ready configuration file in under 60 seconds.

Framework-Specific Templates

CLAUDE.md templates tuned for specific tech stacks:

Specialized Configuration

Environment Variables

Environment variables control Claude Code’s runtime behavior without modifying configuration files. They are essential for CI/CD, Docker, and headless deployments.

Key environment variables:

Variable Purpose
ANTHROPIC_API_KEY API authentication
CLAUDE_MODEL Default model selection
ANTHROPIC_BASE_URL Custom API endpoint (Bedrock, OpenRouter)
HTTP_PROXY / HTTPS_PROXY Proxy configuration

MCP Server Configuration

MCP (Model Context Protocol) servers extend Claude Code’s capabilities with external tools – databases, APIs, cloud services, and more.

Setup Guides

Permission Configuration

Permissions control what Claude Code can read, write, execute, and access. Proper permission configuration is critical for security.

Provider Configuration

Claude Code can connect to different API providers beyond the default Anthropic API.

Frequently Asked Questions

Where does Claude Code store its configuration?

Three locations: project-level at .claude/settings.json (committed to git), user-level at ~/.claude/settings.json (not committed), and CLAUDE.md in your project root. Environment variables override file-based settings. See Config File Location.

What is the difference between settings.json and CLAUDE.md?

settings.json controls Claude Code’s operational behavior (permissions, tools, model selection). CLAUDE.md controls Claude’s understanding of your project (architecture, coding standards, build commands). Both are necessary for a well-configured project.

How do I configure MCP servers?

Add MCP server definitions to your .claude/settings.json file under the mcpServers key. Each server needs a name, transport type (stdio or HTTP), and command or URL. See MCP Configuration Guide.

Can I use Claude Code with AWS Bedrock instead of the Anthropic API?

Yes. Set ANTHROPIC_BASE_URL to your Bedrock endpoint and configure AWS credentials. This gives you data residency control and consolidated AWS billing. See AWS Bedrock Setup.

How do I restrict which files Claude Code can modify?

Use the allowedPaths and disallowedPaths rules in settings.json, and add explicit scoping instructions to your CLAUDE.md. Together, these prevent Claude from modifying sensitive files. See Permission Rules Guide.

What happens if settings.json and CLAUDE.md conflict?

settings.json always takes precedence for operational settings (permissions, tools). CLAUDE.md instructions guide Claude’s behavior within the boundaries set by settings.json. For example, settings.json can block a tool that CLAUDE.md recommends using.

How do I configure Claude Code for a CI/CD pipeline?

Use environment variables for authentication (ANTHROPIC_API_KEY), enable headless mode (--dangerously-skip-permissions), and set the model via CLAUDE_MODEL. See GitHub Actions Setup.

How do I manage settings across multiple team members?

Commit .claude/settings.json and CLAUDE.md to your repository for shared settings. Team members use ~/.claude/settings.json for personal preferences. Enterprise teams can use managed settings for organization-wide policies. See Managed Settings Enterprise.

Related Guides

Best Practices

Proven patterns for effective Claude Code usage

 Error Handling

Fix common Claude Code errors and exceptions

 Troubleshooting

Step-by-step troubleshooting for Claude Code issues

 Getting Started

Quick start guide for new Claude Code users

 Advanced Usage

Power user techniques and advanced workflows
Try our CLAUDE.md Generator → Generate optimized CLAUDE.md files

Master Every Configuration Surface

This reference covers the configuration options. For battle-tested configuration patterns, CLAUDE.md templates for 15 tech stacks, and enterprise deployment playbooks, get the Claude Code Mastery Playbook ($99).