Support hierarchical .claude config discovery in monorepos

Resolved 💬 4 comments Opened Mar 22, 2026 by czechue Closed Mar 25, 2026

Problem

In monorepo setups with multiple apps, each app may have its own .claude/ directory with app-specific skills, hooks, settings, and MCP servers:

<root>
├── .claude/
├── apps/
│   ├── app-frontend-monorepo/
│   │   └── .claude/       # frontend-specific config
│   └── app-backend-monorepo/
│       └── .claude/       # backend-specific config

When Claude Code is launched from the root, it only discovers the root .claude/ config. If the agent starts working on files in app-frontend-monorepo/, it does not pick up that app's .claude/ hooks, settings, or MCP servers.

Current behavior

  • Skills: Auto-discovered from nested .claude/skills/ directories ✅
  • CLAUDE.md: Loaded on-demand from subdirectories ✅
  • Settings (settings.json): Only from repo root ❌
  • Hooks: Only from repo root ❌
  • MCP servers: Session-global, not per-app ❌
  • Permissions: Session-global ❌

Desired behavior

When Claude Code is working on files within a subdirectory that has its own .claude/ directory, it should merge or override the root configuration with the subdirectory's config — similar to how skills and CLAUDE.md already work.

This would mean:

  • Hooks defined in apps/app-frontend-monorepo/.claude/settings.json activate when working in that directory
  • MCP servers scoped to a subdirectory's .claude/ are available when working there
  • Settings can be layered: root provides defaults, subdirectory overrides

Use case

This is essential for monorepos where each app has different:

  • Linting/formatting hooks
  • Dev servers and MCP integrations
  • Permission requirements
  • Testing workflows

Current workarounds

  • Custom subagents per app (partial — no hook/MCP scoping)
  • Path-specific rules (guidance only, not enforcement)
  • Running separate Claude Code sessions per subdirectory (loses monorepo context)

Proposal

Extend the existing scope resolution to support directory-level config discovery, merging configs up the tree (similar to .eslintrc or tsconfig.json resolution):

root/.claude/settings.json          → base config
apps/app-frontend/.claude/settings.json → overrides when working in apps/app-frontend/

This would make Claude Code a first-class citizen in monorepo workflows.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗