Configuration & Settings

Learn to configure Claude Code for your workflow, from managing permissions and authentication to setting up project-specific configurations. This guide covers both personal preferences and team-wide settings.

Configuration Hierarchy

Claude Code uses a hierarchical configuration system that allows flexibility while maintaining consistency:

Settings Precedence (Highest to Lowest)

Enterprise Policies - Managed by IT administrators
Command Line Arguments - Override for specific sessions
Local Project Settings - .claude/settings.local.json
Shared Project Settings - .claude/settings.json
User Settings - ~/.claude/settings.json

Quick Configuration

Interactive configuration
Terminal window
```
claude /config
```
List current settings
Terminal window
```
claude config list
```

Set a specific value

claude config set model claude-sonnet-4
claude config set autoUpdates false --global

View a setting
Terminal window
```
claude config get model
```

Settings Files

User Settings

Global preferences that apply to all projects:

// ~/.claude/settings.json
{
"model": "claude-opus-4",
"theme": "dark",
"autoUpdates": true,
"env": {
  "EDITOR": "code",
  "NODE_ENV": "development"
},
"permissions": {
  "defaultMode": "acceptEdits",
  "allow": [
    "Edit",
    "Bash(git:*)",
    "Bash(npm run:*)"
  ]
}
}

Project Settings

Team-shared configuration checked into version control:

// .claude/settings.json
{
"model": "claude-sonnet-4",
"maxTurns": 20,
"allowedTools": [
  "Edit",
  "View",
  "Bash(npm:*)",
  "mcp__github__*"
],
"env": {
  "API_ENDPOINT": "https://staging.api.company.com"
},
"permissions": {
  "additionalDirectories": [
    "../shared-lib",
    "../api-contracts"
  ]
},
"hooks": {
  "PreToolUse": {
    "Edit": "npm run lint-staged"
  }
}
}

Local Project Settings

Personal overrides not checked into version control:

// .claude/settings.local.json
{
"env": {
  "API_KEY": "your-personal-dev-key"
},
"permissions": {
  "defaultMode": "bypassPermissions"
}
}

Permission Management

Permission Modes

Standard behavior - prompts for permission on first use of each tool:

claude --permission-mode default

Good for: New projects, unfamiliar codebases

Automatically accepts file edit permissions for the session:

claude --permission-mode acceptEdits

Good for: Active development, trusted projects

Read-only analysis without modifications:

claude --permission-mode plan

Good for: Code reviews, architecture analysis

Skip all permission prompts (use with caution):

claude --dangerously-skip-permissions
# or
claude --permission-mode bypassPermissions

Good for: Personal projects, automation scripts

Managing Allowed Tools

Interactive management
Terminal window
```
claude /permissions
```

Allow specific tools

{
  "permissions": {
    "allow": [
      "Edit",                    // All file edits
      "Bash(git:*)",            // All git commands
      "Bash(npm run test:*)",   // Specific npm scripts
      "Read(~/.zshrc)",         // Read specific files
      "mcp__github__*"          // All GitHub MCP tools
    ]
  }
}

Deny dangerous operations

{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",         // Prevent deletions
      "Bash(curl:*)",           // Block external requests
      "Edit(/etc/**)"           // Protect system files
    ]
  }
}

Tool-Specific Rules

Permission Rule Patterns

Tool	Pattern	Example
Bash	`Bash(command:*)`	`Bash(npm run:*)`
Edit	`Edit(path/pattern)`	`Edit(src/**)`
Read	`Read(path/pattern)`	`Read(~/.ssh/*)`
WebFetch	`WebFetch(domain:example.com)`	`WebFetch(domain:api.company.com)`
MCP	`mcp__server__tool`	`mcp__github__create_issue`

Environment Variables

Configuration via Settings

Set environment variables that persist across sessions:

{
"env": {
  // Development settings
  "NODE_ENV": "development",
  "DEBUG": "app:*",

  // API configuration
  "API_BASE_URL": "https://staging.api.com",
  "TIMEOUT": "30000",

  // Tool configuration
  "EDITOR": "code",
  "PAGER": "less"
}
}

Runtime Environment Variables

Override settings for specific sessions:

# Authentication
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_AUTH_TOKEN="Bearer token..."

# Model selection
export ANTHROPIC_MODEL="claude-opus-4"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-3"

# Proxy configuration
export HTTPS_PROXY="https://proxy.company.com:8080"
export NODE_TLS_REJECT_UNAUTHORIZED=0  # Self-signed certs

# Behavior tweaks
export BASH_MAX_TIMEOUT_MS=300000  # 5 minutes
export DISABLE_PROMPT_CACHING=1
export DISABLE_INTERLEAVED_THINKING=1

Model Configuration

Selecting Models

{
  "model": "claude-opus-4",
  "smallFastModel": "claude-haiku-3"
}

export ANTHROPIC_MODEL="claude-sonnet-4"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-3"

claude --model opus
claude --model claude-sonnet-4-20250514

Working Directories

Extend Claude’s file access beyond the launch directory:

During startup
Terminal window
```
claude --add-dir ../backend ../shared
```
During session
Terminal window
```
/add-dir ../documentation
```

Persistent configuration

{
  "permissions": {
    "additionalDirectories": [
      "../api",
      "../shared-components",
      "~/templates"
    ]
  }
}

Enterprise Configuration

Managed Policy Settings

IT administrators can enforce organization-wide settings:

// /etc/claude-code/managed-settings.json (Linux/WSL)
// /Library/Application Support/ClaudeCode/managed-settings.json (macOS)
// C:\ProgramData\ClaudeCode\managed-settings.json (Windows)

{
"permissions": {
  "deny": [
    "Bash(rm -rf:*)",
    "WebFetch(domain:competitor.com)"
  ],
  "disableBypassPermissionsMode": "disable"
},
"env": {
  "CORPORATE_PROXY": "proxy.company.com:8080",
  "CLAUDE_CODE_ENABLE_TELEMETRY": "0"
},
"forceLoginMethod": "console",
"model": "claude-sonnet-4"
}

API Key Management

For enterprise deployments with rotating credentials:

Create key helper script

#!/bin/bash
# Fetch from vault
vault kv get -field=api_key secret/claude-code

# Or from AWS Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id claude-code-api-key \
  --query SecretString --output text

Configure Claude Code

{
  "apiKeyHelper": "~/bin/get-api-key.sh"
}

Set refresh interval

export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000  # 1 hour

Advanced Settings

Hooks Configuration

Automate workflows with pre/post tool hooks:

{
"hooks": {
  "PreToolUse": {
    "Edit": "npm run pre-edit-checks",
    "Bash": "echo 'Executing: $COMMAND'"
  },
  "PostToolUse": {
    "Edit": "npm run format",
    "MultiEdit": "git add -A"
  }
}
}

Custom Slash Commands

Create reusable commands in .claude/commands/:

---
name: test-component
description: Run tests for a React component
---

npm test -- --testNamePattern="$ARGUMENTS" --coverage

MCP Server Configuration

Configure Model Context Protocol servers:

{
"mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  },
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://localhost/mydb"
    ]
  }
}
}

Troubleshooting Configuration

Common Issues

Check precedence order:

# View effective settings
claude config list

# Check which file is being used
claude config get model -v

Ensure proper file permissions:

# Fix user settings
chmod 600 ~/.claude/settings.json

# Fix project settings
chmod 644 .claude/settings.json

Validate your settings files:

# Use Claude's built-in validator
claude /doctor

# Or validate manually
jq . ~/.claude/settings.json

Best Practices

Configuration Tips

Start with defaults - Only override what you need
Use project settings - Share common configurations with your team
Keep secrets local - Use .claude/settings.local.json for API keys
Document custom settings - Add comments in your CLAUDE.md
Review permissions regularly - Audit allowed tools periodically
Use environment variables - For temporary overrides
Leverage hooks - Automate repetitive tasks
Test configurations - Verify settings work across team members

Next Steps

Initialize Your First Project Create a CLAUDE.md file and set up project context

IDE Integration Connect Claude Code with your favorite editor

Configuration Reference

Setting	Type	Scope	Description
`model`	string	All	Primary model selection
`autoUpdates`	boolean	Global	Enable auto-updates
`theme`	string	Global	UI theme (dark/light)
`permissions`	object	All	Permission rules
`env`	object	All	Environment variables
`hooks`	object	All	Tool execution hooks
`allowedTools`	array	All	Permitted tools list
`additionalDirectories`	array	All	Extra working directories
`cleanupPeriodDays`	number	All	Chat history retention