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.
{
"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 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
# 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.
{
"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 *)"
]
}
}
* 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 |
# 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.
{
"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"
}
}
}
}
Custom Slash Commands
You can define your own slash commands to automate repetitive tasks. Custom commands are defined in your project's .claude/ directory.
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
# Use your custom command Claude > /review-pr # Custom commands with arguments (use $ARGUMENTS placeholder) Claude > /review-pr --focus security
/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.
{
"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 |
# 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:
- Create a
CLAUDE.mdfile in your project root with your coding conventions - Create a custom slash command in
.claude/commands/for a task you do frequently - Add a few safe commands to the allow list in your settings
- Try switching between Claude models using
/model
Lilly Tech Systems