[FEATURE] Settings.json parent directory traversal for monorepos

[skorfmann]

Problem

When working in a monorepo subdirectory (e.g., /repo/packages/app/), Claude Code only looks for .claude/settings.json in the current working directory. It does not traverse parent directories to find shared settings at the repo root.

This means you either need to:

• Duplicate settings in every subdirectory
• Always launch Claude Code from the repo root
• Use global user settings (~/.claude/settings.json) which apply to all projects

Proposed Solution

Claude Code should traverse parent directories (up to the git root or filesystem root) looking for .claude/settings.json files, similar to how many tools handle config files (e.g., .gitignore, tsconfig.json, .eslintrc).

Settings could be merged with deeper directories taking precedence, or the first found settings file could be used.

Use Case

In a monorepo with multiple packages/services, you want shared settings (allowed tools, MCP servers, permissions) defined once at the repo root, while still being able to work from within subdirectories.

Related Issues

• [FEATURE] Better Monorepo Support #2365 - Better Monorepo Support (MCP and commands)
• Feature Request: MCP repo scope #374 - MCP repo scope
• [FEATURE REQUEST] Nested CLAUDE.md context #705 - Nested CLAUDE.md context
• Feature Request: Configure Additional Directories via Settings Files #3146 - Configure additional directories via settings files

This issue focuses specifically on settings.json lookup behavior, complementing the related requests for MCP, commands, and CLAUDE.md parent directory support.

[skorfmann]

Workaround: Using Mise for per-project environment variables

While waiting for native parent directory traversal, you can use Mise to manage per-project environment variables that Claude Code will pick up.

Setup

1. Install mise and activate it in your shell:

   # Install (macOS)
   brew install mise
   
   # Add to ~/.zshrc or ~/.bashrc
   eval "$(mise activate zsh)"

2. Add a .mise.toml at your repo root:

   [env]
   _.file = ".env"  # optional: load secrets from .env
   
   # Claude Code OTEL config (example)
   CLAUDE_CODE_ENABLE_TELEMETRY = "1"
   OTEL_METRICS_EXPORTER = "otlp"
   OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318"

3. When you cd into any subdirectory, mise automatically injects env vars from parent .mise.toml files.

Why this works

Mise traverses parent directories and merges configs - exactly what we're requesting for settings.json. This covers environment variable needs but not Claude Code-specific settings like allowed tools or MCP servers.

[github-actions]

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.

[madhermit]

I'm still interested in this addition

[roccolangeweg]

Adding another use case beyond monorepos:

Multi-Client Consultancy Setup

As a consultant working with multiple clients, my repository structure is:

~/Repositories/
├── client-a/
│   ├── .claude/
│   │   ├── settings.json      # Client A's permissions, hooks
│   │   ├── .mcp.json          # Client A's Slack workspace, APIs
│   │   └── CLAUDE.md          # Client A's coding standards
│   ├── repo-1/
│   ├── repo-2/
│   └── repo-3/
│
├── client-b/
│   ├── .claude/
│   │   ├── settings.json      # Client B's different config
│   │   ├── .mcp.json          # Client B's Slack workspace, APIs
│   │   └── CLAUDE.md
│   └── ...

Current limitation: When I cd ~/Repositories/client-a/repo-1 and run claude, only CLAUDE.md is picked up from the parent client directory. The settings.json and .mcp.json at client level are ignored.

Desired behavior: Parent directory traversal for settings.json and .mcp.json (similar to how CLAUDE.md already works), with repo-level configs taking precedence for overrides.

This would allow:

• Client-specific MCP servers (different Slack workspaces, Jira instances, etc.)
• Client-specific permissions and hooks
• Repo-specific overrides when needed

Currently the only workarounds are symlinks (which break repo-level overrides) or duplicating config in every repo.