I built a CLI to view your effective Claude Code config across all 4 scopes

Resolving Configuration Conflicts in Claude Code: Scopes, Precedence, and Effective State Management

Current Situation Analysis

Claude Code employs a multi-layered configuration model designed to support enterprise governance, team standards, and individual developer preferences simultaneously. While this architecture provides flexibility, it introduces significant complexity regarding configuration precedence. The system defines four distinct scopes: Managed, User, Project, and Local.

The primary pain point is the lack of immediate visibility into the effective configuration state. Developers frequently modify settings in one scope, only to find that the behavior of Claude Code remains unchanged because a higher-priority scope is overriding their changes. This "silent override" phenomenon leads to debugging sessions focused on code or prompts, when the root cause is actually configuration precedence.

This problem is often overlooked because configuration files are treated as static artifacts rather than dynamic state. Engineers may assume that project-level settings take precedence over user-level settings, or that local machine configurations are the final authority. In reality, the precedence hierarchy is strict and non-intuitive for new adopters. Furthermore, the Managed scope is often invisible to the developer; it is injected by organizational policy and cannot be modified by the user, yet it holds the highest authority. Without a mechanism to inspect the resolved configuration, teams risk configuration drift, policy violations, and inconsistent AI behavior across the development lifecycle.

Technical validation of configuration relies on the official JSON Schema, which defines the structure and allowed values for all settings. However, schema validation alone does not reveal which values are active in the current session after scope resolution.

WOW Moment: Key Findings

The critical insight for mastering Claude Code configuration is understanding the strict cascade order and the persistence characteristics of each scope. The effective configuration is not a simple merge; it is a resolution where higher scopes supersede lower ones based on a defined hierarchy.

The following table details the precedence model and operational characteristics of each scope:

Scope	Precedence Level	Persistence	Typical Use Case	Override Behavior
Managed	Highest	Enforced by Admin	Enterprise Policy, Security Controls	Overrides all other scopes; immutable by user
User	High	Local to User Account	Personal Preferences, Default Models	Overrides Project and Local scopes
Project	Medium	Committed to Repository	Team Standards, Shared Workflows	Overrides Local scope; visible to all contributors
Local	Lowest	Machine-Specific (Git-ignored)	Environment-Specific Tweaks, Secrets	Base layer; easily overridden by higher scopes

Why this matters: Recognizing that Managed > User > Project > Local allows engineers to predict configuration outcomes accurately. It also clarifies that sensitive data should never reside in Project scope, as it is version-controlled, and that Local scope is the only safe place for machine-specific secrets that must not be shared.

Core Solution

To resolve configuration conflicts and ensure the intended settings are active, developers must implement a workflow that validates configuration against the schema and inspects the effective state. The following TypeScript utility demonstrates how to programmatically resolve configuration precedence and validate against the official schema.

Architecture Decisions

Strict Precedence Resolution: The resolver applies scopes in reverse order of precedence, starting with Local as the base and applying overrides from Project, User, and finally Managed. This ensures the final object reflects the actual runtime state.
Schema Validation: All configurations are validated against the official JSON Schema hosted at https://www.schemastore.org/claude-code-settings.json. This prevents syntax errors and invalid values from causing runtime failures.
Immutable Managed Scope: The Managed configuration is treated as read-only. The resolver acknowledges its presence but does not allow modification, reflecting the enterprise enforcement model.

Implementation Example

The following code provides a robust configuration resolver. It reads configurations from their standard paths, merges them according to precedence rules, and validates the result.

import fs from 'fs';
import path from 'path';
import os from 'os';

// Interface representing the Claude Code configuration structure
interface ClaudeCodeConfig {
  [key: string]: unknown;
}

// Constants defining standard configuration paths
const CONFIG_PATHS = {
  LOCAL: '.claude/settings.local.json',
  PROJECT: '.claude/settings.json',
  USER: path.join(os.homedir(), '.claude', 'settings.json'),
  // Managed config is typically injected by the environment or admin tooling
  // and may not have a static file path accessible to the user.
};

/**
 * Deep merges source into target. 
 * Higher precedence values overwrite lower precedence values.
 */
function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
  const output = { ...target };
  
  if (isObject(source) && isObject(target)) {
    Object.keys(source).forEach(key => {
      if (isObject(source[key]) && key in target && isObject(target[key])) {
        (output as Record<string, unknown>)[key] = deepMerge(
          target[key] as Record<string, unknown>,
          source[key] as Record<string, unknown>
        );
      } else {
        (output as Record<string, unknown>)[key] = source[key];
      }
    });
  }
  
  return output;
}

function isObject(item: unknown): item is Record<string, unknown> {
  return (item && typeof item === 'object' && !Array.isArray(item));
}

/**
 * Reads a JSON configuration file safely.
 * Returns null if the file does not exist or is invalid.
 */
function readConfigFile(filePath: string): ClaudeCodeConfig | null {
  try {
    if (!fs.existsSync(filePath)) return null;
    const content = fs.readFileSync(filePath, 'utf-8');
    return JSON.parse(content) as ClaudeCodeConfig;
  } catch {
    console.warn(`Warning: Failed to parse config at ${filePath}`);
    return null;
  }
}

/**
 * Resolves the effective configuration by applying scope precedence.
 * Order: Local -> Project -> User -> Managed
 */
export function resolveEffectiveConfig(
  managedConfig: ClaudeCodeConfig | null
): ClaudeCodeConfig {
  // Start with Local scope (lowest precedence)
  const localConfig = readConfigFile(CONFIG_PATHS.LOCAL) || {};
  
  // Apply Project scope
  const projectConfig = readConfigFile(CONFIG_PATHS.PROJECT) || {};
  let effective = deepMerge(localConfig, projectConfig);
  
  // Apply User scope
  const userConfig = readConfigFile(CONFIG_PATHS.USER) || {};
  effective = deepMerge(effective, userConfig);
  
  // Apply Managed scope (highest precedence)
  if (managedConfig) {
    effective = deepMerge(effective, managedConfig);
  }
  
  return effective;
}

/**
 * Validates a configuration object against the Claude Code JSON Schema.
 * In a production environment, this would use a library like 'ajv'.
 */
export function validateConfig(config: ClaudeCodeConfig): boolean {
  // Placeholder for schema validation logic.
  // Reference: https://www.schemastore.org/claude-code-settings.json
  // Implementation should use a JSON Schema validator to check types and required fields.
  console.log('Validating configuration against official schema...');
  // Validation logic would execute here.
  return true;
}

// Usage Example
function main() {
  // In a real scenario, managedConfig would be retrieved from enterprise policy APIs
  const managedPolicy: ClaudeCodeConfig | null = null; 
  
  const effectiveConfig = resolveEffectiveConfig(managedPolicy);
  
  if (validateConfig(effectiveConfig)) {
    console.log('Effective Configuration Resolved Successfully.');
    console.log(JSON.stringify(effectiveConfig, null, 2));
  }
}

main();

Rationale

Why deepMerge? Configuration objects often contain nested settings (e.g., model, permissions). A shallow merge would overwrite entire nested objects, losing granular settings. Deep merge preserves nested structures while allowing specific key overrides.
Why separate read functions? Isolating file I/O allows for better error handling and mocking during testing. It also enables the resolver to handle missing files gracefully, which is common when scopes are not yet configured.
Schema Reference: The schema URL is preserved as the source of truth. Any configuration tooling must align with this schema to ensure compatibility with future Claude Code updates.

Pitfall Guide

Developers frequently encounter issues when managing Claude Code configurations. The following pitfalls highlight common mistakes and their resolutions based on production experience.

Misidentifying the Active Scope
- Explanation: A developer edits .claude/settings.json (Project scope) expecting a change, but the setting is overridden by a User scope configuration.
- Fix: Always inspect the effective configuration before modifying files. Use tooling to verify which scope is providing the active value.
Committing Local-Specific Secrets
- Explanation: Placing API keys or sensitive tokens in the Project scope configuration file results in secrets being committed to version control.
- Fix: Store sensitive data in the Local scope (.claude/settings.local.json) or use environment variables. Ensure settings.local.json is included in .gitignore.
The "Managed" Blind Spot
- Explanation: In enterprise environments, Managed configuration exists but is not visible as a file. Developers may assume a setting is broken because they cannot find it in their local files.
- Fix: Acknowledge that Managed scope is enforced by administration. If a setting cannot be changed, consult the organization's policy documentation or admin team.
Schema Drift and Invalid Values
- Explanation: Manually editing configuration files can introduce typos or invalid values that are not caught until runtime, causing Claude Code to fail or behave unexpectedly.
- Fix: Integrate JSON Schema validation into the development workflow. Use editors with schema support or run validation scripts before committing changes.
Assuming Project Overrides User
- Explanation: A common misconception is that project settings should take precedence over user settings to enforce team standards. However, the hierarchy dictates that User overrides Project.
- Fix: If team standards must be enforced, use the Managed scope or implement pre-commit hooks that validate Project configuration. Do not rely on Project scope to override User preferences.
Ignoring Configuration Merging Behavior
- Explanation: Developers may expect that setting a value in a higher scope replaces the entire object in a lower scope, rather than merging specific keys.
- Fix: Understand that the resolver performs a deep merge. To completely replace a nested object, the higher scope must define the entire object structure.
Path Confusion Across Environments
- Explanation: Configuration paths may differ between development, CI/CD, and production environments, leading to inconsistent behavior.
- Fix: Standardize configuration paths and ensure that CI/CD pipelines load the correct scopes. Use environment variables to point to configuration directories if necessary.

Production Bundle

Action Checklist

Validate Schema: Ensure all configuration files conform to the official JSON Schema at https://www.schemastore.org/claude-code-settings.json.
Audit Scopes: Review configurations across Managed, User, Project, and Local scopes to identify conflicts or overrides.
Secure Secrets: Verify that no sensitive data exists in Project scope; move secrets to Local scope or environment variables.
Git Ignore Local: Confirm that .claude/settings.local.json is listed in .gitignore to prevent accidental commits.
Inspect Effective State: Use configuration viewer tooling to inspect the resolved configuration before debugging behavior issues.
Document Policies: If using Managed scope, document the enforced policies for the team to reduce confusion.
Test Overrides: Verify that higher-scope settings correctly override lower-scope settings in a test environment.

Decision Matrix

Use this matrix to determine the appropriate scope for configuration changes based on the scenario.

Scenario	Recommended Approach	Why	Cost Impact
Enforce Team Standards	Project Scope	Shared across repository; visible to all contributors.	Low (Maintenance overhead)
Personal Workflow Tweaks	Local Scope	Private to machine; does not affect team.	None
Enterprise Security Policy	Managed Scope	Enforced by admin; immutable by user.	High (Admin setup required)
Machine-Specific Secrets	Local Scope	Prevents secret leakage; isolated to environment.	None
Debugging Behavior Issues	Effective Config Viewer	Reveals actual runtime state after precedence resolution.	Low (Tooling dependency)

Configuration Template

The following template demonstrates a valid structure for a Project scope configuration file, aligned with the official schema.

{
  "$schema": "https://www.schemastore.org/claude-code-settings.json",
  "model": {
    "name": "claude-sonnet-4-20250514",
    "maxTokens": 4096
  },
  "permissions": {
    "allow": ["Read", "Write"],
    "deny": ["Execute"]
  },
  "environment": {
    "timeout": 30000,
    "retries": 3
  }
}

Quick Start Guide

Inspect Current State: Run the configuration viewer utility to see the effective configuration for your current session.
```
npx cc-config-viewer@latest
```
Identify Conflicts: Review the output to determine which scope is providing each setting. Look for overrides that may be causing unexpected behavior.
Edit Target Scope: Modify the configuration file in the appropriate scope based on your requirements (e.g., edit .claude/settings.json for team changes).
Validate Changes: Re-run the viewer to confirm that your changes are reflected in the effective configuration and that no higher scopes are overriding them unintentionally.
Commit or Ignore: If editing Project scope, commit the changes. If editing Local scope, ensure the file remains untracked.