[FEATURE] Directory-level settings inheritance (apply settings to all child projects)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, Claude Code settings exist at three levels: global (~/.claude/settings.json), project (.claude/settings.json), and local (.claude/settings.local.json). There's no way to apply settings to a group of related projects under a common parent directory.

My use case: I have a directory of learning projects (~/projects/learning/) where I want outputStyle: "learning" applied automatically. Today I either have to set it globally (affecting all projects) or configure each project individually. Neither scales well — global is too broad, and per-project is repetitive.

This applies beyond output styles to any setting (permissions, environment variables, etc.) where you'd want a shared configuration for a group of projects.

Proposed Solution

Add a new settings scope between "user" and "project" that applies to all child directories. When Claude Code resolves settings, it would walk up from the current working directory looking for .claude/settings.json files in ancestor directories, merging them with the existing precedence chain:

managed > local > project > parent directories (nearest first) > user

For example, placing .claude/settings.json in ~/projects/learning/ would apply those settings to every project opened from within that directory tree, while still allowing per-project overrides

Alternative Solutions

• Monorepo approach: Restructure projects into a single repo so the project-level setting covers everything. Works but forces a repo structure decision based on tooling rather

than project organization.

• Global + per-project overrides: Set the desired style globally and override in projects that need something different. Inverts the mental model when the style only applies to

a subset of projects.

• Scripting: Run a shell script to create .claude/settings.local.json in each subdirectory. Fragile — breaks when adding new projects.

Priority

Low - Nice to have

Feature Category

Configuration and settings

Use Case Example

1. I have ~/projects/learning/ with 10+ small projects for studying different topics
2. I place .claude/settings.json in ~/projects/learning/ with {"outputStyle": "learning"}
3. I cd ~/projects/learning/rust-exercises && claude — learning mode is active
4. I cd ~/projects/learning/algorithms && claude — learning mode is active
5. I cd ~/projects/work/app && claude — default mode, unaffected
6. If one learning project needs different settings, its own .claude/settings.local.json still takes precedence

Additional Context

This pattern is well-established in other tools — .gitconfig, .editorconfig, .eslintrc, and tsconfig.json all support directory-based inheritance by walking up the file tree.

The existing CLAUDE.md already supports parent-directory loading, so extending this to settings.json would be consistent with that behavior.