Claude Code Configuration

Overview

Claude Code provides hierarchical configuration through settings.json files at multiple levels. You can manage settings globally, per-project, or through enterprise policies.

Configuration File Locations

User-level settings: ~/.claude/settings.json (applies to all projects)

Project-level settings:

• .claude/settings.json (shared with team via source control)
• .claude/settings.local.json (personal, not committed)

Enterprise managed policies:

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

Key Configuration Options

Setting	Purpose	Example
permissions	Control tool access and file restrictions	{"allow": ["Bash(npm run test:*)"], "deny": ["Read(.env)"]}
env	Environment variables for sessions	{"FOO": "bar"}
model	Override default model	"claude-sonnet-4-5-20250929"
outputStyle	Adjust system prompt behavior	"Explanatory"
hooks	Custom commands before/after tool use	{"PreToolUse": {"Bash": "echo 'Running..'"}}

Permission Configuration

Restrict file and command access through the permissions object:

Deny patterns block sensitive files:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)",
      "Bash(curl:*)"
    ]
  }
}

Allow patterns explicitly permit actions:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)"
    ]
  }
}

Ask patterns require confirmation:

{
  "permissions": {
    "ask": [
      "Bash(git push:*)",
      "Write(src/**)"
    ]
  }
}

Sandbox Settings

Enable process isolation (macOS/Linux):

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

Settings Precedence (High to Low)

1. Enterprise managed policies
2. Command-line arguments
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

Environment Variables

Key variables for controlling Claude Code behavior:

• ANTHROPIC_API_KEY - API authentication
• BASH_MAX_OUTPUT_LENGTH - Limit bash output size
• DISABLE_TELEMETRY - Opt out of analytics
• MAX_THINKING_TOKENS - Enable extended thinking
• CLAUDE_CODE_USE_BEDROCK - Use AWS Bedrock
• DISABLE_PROMPT_CACHING - Turn off caching globally

Available Tools

Claude Code can access these tools (subject to permissions):

• Bash
• Edit, Read, Write
• WebFetch, WebSearch
• Glob, Grep
• NotebookEdit
• Task

Plugin Management

Configure plugins via enabledPlugins:

{
  "enabledPlugins": {
    "formatter@company-tools": true,
    "deployer@company-tools": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  }
}

Access plugin management interactively with /plugin command.

Excluding Sensitive Files

Prevent Claude from accessing confidential data:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(./secrets/**)",
      "Read(**/credentials.json)"
    ]
  }
}

Files matching deny patterns become completely invisible to Claude Code.

Common Configuration Examples

Development Team Setup

.claude/settings.json (committed to repo):

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(.env*)",
      "Bash(git push:*)"
    ],
    "ask": [
      "Write(src/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Personal Overrides

.claude/settings.local.json (not committed):

{
  "model": "claude-opus-4-5-20250514",
  "env": {
    "CUSTOM_VAR": "my-value"
  }
}

Enterprise Security Policy

/etc/claude-code/managed-settings.json:

{
  "permissions": {
    "deny": [
      "Read(/etc/passwd)",
      "Read(~/.ssh/**)",
      "Bash(rm:*)",
      "Bash(sudo:*)"
    ]
  },
  "sandbox": {
    "enabled": true
  }
}

Managing Settings

View current settings: Check the files in .claude/ directory

Edit project settings: Create or modify .claude/settings.json

Edit user settings: Modify ~/.claude/settings.json

Interactive configuration: Some settings can be managed via slash commands like /permissions

Best Practices

1. Use project settings for team-shared configuration
2. Use local settings for personal preferences
3. Commit shared settings to source control
4. Document settings with comments (use // in JSON5-compatible editors)
5. Review permissions regularly for security
6. Test settings before enforcing team-wide
7. Use deny patterns for sensitive files
8. Enable sandbox for additional security
9. Set environment variables for consistent environments
10. Configure marketplaces for team plugin distribution

Troubleshooting

Settings not applying:

• Check file locations and names
• Verify JSON syntax
• Review precedence order
• Check for conflicting settings at different levels

Permission errors:

• Review deny/allow patterns
• Check pattern syntax (glob patterns supported)
• Verify file paths are correct
• Test patterns incrementally

Plugin issues:

• Verify marketplace configuration
• Check plugin names and versions
• Ensure plugins are enabled in enabledPlugins
• Review plugin-specific settings