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

Status Fixed / completed

Maintainer reply None cached

Workaround ✓ Mentioned in thread ↓

Activity 6 comments · opened Jul 25, 2025 · closed Jan 17, 2026

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):

Default Settings (Hardcoded in the application)
User Settings (~/.claude/settings.json)
Local Project Settings (<project>/.claude/settings.local.json) - (Not checked into git)
Project Settings (<project>/.claude/settings.json) - (Checked into git)
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

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.
Implement the merge logic carefully to ensure system-level settings correctly override user/project settings.
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.

View original on GitHub ↗

6 Comments

gwpl · 1 year ago

AI Assistant:

This hierarchical configuration proposal becomes even more critical with the upcoming rate limits. I've created issue #4807 that specifically addresses model selection within your proposed configuration hierarchy.

Your proposed precedence order (Default → User → Local Project → Project → Managed) would be perfect for implementing granular model controls:

// Default Settings
{ "model": "sonnet" }

// User Settings (~/.claude/settings.json)
{ "model": "sonnet", "opus_quota_threshold": 0.8 }

// Project Settings (.claude/settings.json)
{ 
  "model": "opus",
  "model_rules": [
    { "pattern": "*.rs", "model": "opus" },
    { "pattern": "*.md", "model": "sonnet" }
  ]
}

// Managed Settings (Enterprise)
{ "model_quota_enforcement": true, "max_opus_hours_per_week": 20 }

With only 24-40 Opus hours per week (starting August 28), we need this hierarchical system to support:

Organization-wide quota policies
Project-specific model preferences
User overrides for specific workflows
Dynamic model selection rules

Please see #4807 for specific model selection features that would integrate perfectly with your hierarchical configuration system.

github-actions[bot] · 1 year ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

github-actions[bot] · 8 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

greghughespdx · 7 months ago

Use Case: Global hooks ignored when project-local hooks are defined

I'm hitting this with hooks specifically. My setup:

Global settings (~/.claude/settings.json): defines a SessionStart hook
Project-local settings (.claude/settings.local.json): defines PreToolUse, Stop, and Notification hooks (for a Slack integration)

Expected behavior: All hooks from both files should merge and run (per the documentation: "Multiple hooks from different sources can respond to the same event").

Actual behavior: Only the project-local hooks run. The global SessionStart hook is completely ignored - no execution, no errors, just silent skip.

Evidence:

Project-local hooks (PreToolUse, Stop, Notification): debug logs exist, working ✅
Global hook (SessionStart): no log, no context injection ❌

Workaround: Duplicate the global hook into every project's local settings file - exactly the anti-pattern this issue describes.

This suggests hooks are being replaced at the object level rather than merged at the hook-type level when a project has its own hooks section.

coygeek · 7 months ago

Post Update:

As the original author of this issue, I’ve been tracking the daily documentation updates and it looks like this request has been fully addressed and implemented.

The latest documentation (as of 2026-01-16) confirms that a unified hierarchical configuration system is now a core feature of Claude Code. It has evolved even further than my initial proposal.

Here is the breakdown of what has been updated:

1. Unified Precedence & Scopes

The documentation now explicitly defines Configuration Scopes and Settings Precedence in a central location (/docs/en/settings). The hierarchy is exactly as requested, with Managed settings taking absolute precedence:

Managed settings (System-level, highest authority)
Command line arguments
Local project settings (.claude/settings.local.json)
Shared project settings (.claude/settings.json)
User settings (~/.claude/settings.json)

2. System-Wide Paths

The suggested paths for managed-settings.json and managed-mcp.json are now officially documented for all platforms:

macOS: /Library/Application Support/ClaudeCode/
Linux/WSL: /etc/claude-code/
Windows: C:\Program Files\ClaudeCode\

3. Administrative "Lock-Down" Capabilities

The system now goes beyond simple merging. Administrators can now enforce specific security-critical policies that users cannot override:

allowManagedHooksOnly: If set to true in managed settings, Claude will ignore all user, project, and plugin hooks, ensuring only corporate-approved scripts run.
strictKnownMarketplaces: Allows admins to allowlist specific plugin sources (GitHub repos, NPM packages, etc.) or block new plugin additions entirely.
allowedMcpServers / deniedMcpServers: Provides exclusive or policy-based control over which MCP servers can be accessed, effectively preventing the use of unauthorized third-party tools.
disableBypassPermissionsMode: Allows admins to disable the --dangerously-skip-permissions flag at the system level.

4. Consolidated Documentation

The configuration system is no longer siloed in the Monitoring section. All details regarding hierarchy, scope, and specific keys (attribution, permissions, environment variables, etc.) are consolidated in a dedicated Settings reference page.

Conclusion

This implementation provides the exact "final say" authority required for enterprise deployment. Since the requested functionality is now live and well-documented, I am satisfied with the resolution of this feature request.

Status: Resolved / Implemented.

github-actions[bot] · 7 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.