Feature Request: Add extends field to settings.json for shared configuration inheritance

Problem

Teams sharing Claude Code configurations (commands, agents, hooks, CLAUDE.md) across multiple repositories currently must manually copy files between projects. This leads to configuration drift and maintenance burden as teams scale.

Proposed Solution

Add an extends field to .claude/settings.json that allows inheriting from shared configurations, similar to ESLint and TSConfig:

{
  "extends": "@ourteam/claude-config"
}

Supported Sources

1. NPM packages: "@ourteam/claude-config" - uses existing npm auth
2. Local paths: "../shared/claude-config" - for monorepos
3. Git URLs: "github:ourteam/shared-claude-config" - uses system git credentials

How It Works

Shared Config Structure

@ourteam/claude-config/
├── package.json         # For npm distribution
├── CLAUDE.md           # Shared context and patterns
├── commands/
│   ├── deep-review.md
│   └── jira-worktree.md
├── agents/
│   └── git-workflow-expert.md
└── settings.json        # Shared settings

Resolution Rules

1. Commands/Agents: Union of all sources (local + shared)

• Local files with same name override shared ones
• All unique files from both sources are available

1. Settings.json: Deep merge with local precedence

```json
// Shared settings.json
{"permissions": {"allow": ["git commit", "git push"]}}

// Local settings.json
{"extends": "@ourteam/claude-config", "permissions": {"allow": ["npm test"]}}

// Result: allow = ["git commit", "git push", "npm test"]
```

1. CLAUDE.md: Concatenated with clear source indication

• Shared CLAUDE.md content loads first (foundational context)
• Local CLAUDE.md content follows (project-specific context)
• Both are included in Claude's context at startup

Multiple Inheritance

Support for extending multiple configurations:

{
  "extends": [
    "@company/claude-base",     // Company-wide standards
    "@team/claude-backend"      // Team-specific backend patterns
  ]
}

Resolution order: Later sources override earlier ones, local config overrides all.

Authentication

• NPM packages: Uses existing npm login credentials
• Git repos: Uses existing system git credentials (SSH keys, credential helpers)
• No new authentication configuration required

Error Handling

• Missing package: Clear error message with installation instructions
• Authentication failure: Falls back to local-only configuration
• Network issues: Uses cached version if available
• Conflicts: Local files always take precedence, with optional warnings

Benefits

• Teams maintain shared resources in one place
• Updates propagate automatically via npm update or git pull
• Version control for team configurations
• Follows familiar patterns from ESLint, TSConfig, Prettier
• Backwards compatible - existing projects work unchanged

Example Use Case

A team maintains @acme/claude-shared with:

• Shared CLAUDE.md containing coding standards, architecture patterns, and team conventions
• Common commands like deep-review, jira-worktree, and test-runner
• Standard git workflow agents

Each project simply adds "extends": "@acme/claude-shared" to their settings.json and gets all shared context and commands while keeping project-specific configurations local.

Related Issues

• #3146 - Feature Request: Configure Additional Directories via Settings Files
• #238 - Auto-load CLAUDE.md files from submodules
• #515 - MCP servers defined in global.json are not applied to projects

This proposal complements these by providing a unified, versioned approach to configuration sharing across independent repositories.