Feature Request: Implement Unified Hierarchical Configuration with System-Wide Managed Settings

Title: Feature Request: Implement Unified Hierarchical Configuration with System-Wide Managed Settings

Labels: feature-request, enhancement, configuration, enterprise

Body

Is this a bug report or a feature request?

Feature Request

Problem Statement

Currently, Claude Code's configuration is primarily handled at the user (~/.claude/settings.json) and project (.claude/settings.json) levels. While this is great for individual developers, it presents significant challenges for team and enterprise environments where administrators need to enforce security policies, set corporate-wide defaults, and ensure consistent telemetry and tooling.

The current model lacks a system-wide configuration layer that can set non-overridable base policies for all users on a machine. This capability is critical for corporate adoption, security compliance, and operational consistency.

Evidence from Current Documentation

The concept of managed settings already exists in a limited capacity. The Monitoring documentation describes an "Administrator Configuration" using a managed-settings.json file to enforce OpenTelemetry settings.

However, this powerful concept is not presented as a unified, top-level feature of the configuration system. It seems siloed to telemetry, and the overall precedence of settings files is not clearly documented in a central location.

Proposed Solution

I propose formalizing and expanding the managed-settings.json concept into a unified, hierarchical configuration system that applies to all settings, not just telemetry.

The configuration should be loaded with a clear and well-documented order of precedence, where settings from higher-precedence files merge with and override those from lower-precedence files. The key requirement is that the system-wide managed settings should be the highest authority to allow administrators to enforce policies.

1. Formalize System-Wide Managed Settings:
Introduce a system-level settings file that is loaded first and has the highest precedence. Based on the existing monitoring docs, the paths should be:

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

2. Establish a Clear Order of Precedence:
The final effective configuration should be a result of merging settings in the following order (where items lower in the list override those above them, except for specific keys that an administrator might want to lock down):

1. Default Settings (Hardcoded in the application)
2. User Settings (~/.claude/settings.json)
3. Local Project Settings (<project>/.claude/settings.local.json) - (Not checked into git)
4. Project Settings (<project>/.claude/settings.json) - (Checked into git)
5. Managed Settings (System-wide) (/etc/claude-code/managed-settings.json, etc.)

Correction based on enterprise needs: For true administrative control as requested, Managed Settings must have the final say on specific, security-critical keys. The merge logic should be: Defaults <- User <- Local Project <- Project, and then Managed settings are applied on top, overriding any conflicting keys. This ensures policies are enforced.

Example Use Case (Enterprise Administrator)

An administrator wants to ensure all developers use the corporate proxy and send telemetry to a specific endpoint.

They would create /etc/claude-code/managed-settings.json with the following content:

{
  "proxy": "http://proxy.my-corp.com:8080",
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://telemetry.my-corp.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  },
  "permissions": {
    "allowedTools": [
      "Bash(rm*:*)", // Example: explicitly deny `rm`
      "Bash(curl*:*)" // Example: explicitly deny `curl`
    ],
    "deniedTools": true // This is a hypothetical flag to lock down tool permissions
  }
}

These settings would apply to all claude sessions on that machine and could not be overridden by a user's or project's settings.json.

Developer Experience

A developer on that machine can still set their personal preferences in ~/.claude/settings.json for non-conflicting settings:

{
  "model": "claude-3-5-sonnet-20240620",
  "temperature": 0.5
}

The resulting configuration for their session would be a combination of both files, with the admin's proxy and telemetry settings enforced.

Implementation Suggestions

1. Refactor the loadSettings function (likely in packages/cli/src/config/settings.ts) to detect and load all configuration files in the specified order of precedence.
2. Implement the merge logic carefully to ensure system-level settings correctly override user/project settings.
3. Update the primary configuration documentation to clearly explain this hierarchical model, the file locations, and the precedence order. This would consolidate information currently scattered across pages like the Hooks Reference and Monitoring.

By implementing this feature, Claude Code will become significantly more secure, manageable, and appealing for enterprise deployment, directly addressing a key requirement for team-based development workflows.