Feature Request: Configure Additional Directories via Settings Files

Feature Request: Configure Additional Directories via Settings Files

Problem Description

Currently, the only way to give Claude Code access to directories outside the current working directory is through:

• CLI flag: --add-dir /path/to/directory when launching Claude Code
• Slash command: /add-dir /path/to/directory during a session

This creates friction for developers who regularly work with:

• Monorepos with multiple services
• Projects that reference shared libraries
• Frontend/backend split architectures
• Legacy systems during migrations

Additionally, there's inconsistent behavior with CLAUDE.md files - they're not automatically read from directories added via --add-dir, which can be confusing and limits the ability to provide context for additional directories.

Having to remember and type multiple --add-dir flags every time Claude Code is launched is error-prone and inefficient.

Proposed Solution

Allow additional directories to be configured in Claude Code's settings files with granular control over CLAUDE.md processing:

// ~/.claude/settings.json or .claude/settings.json
{
  "additionalDirectories": [
    // Simple string format (default: don't read CLAUDE.md)
    "../backend",
    
    // Object format with explicit CLAUDE.md control
    {
      "path": "../shared-components",
      "readClaudeMd": true
    },
    {
      "path": "~/company/templates",
      "readClaudeMd": false
    },
    {
      "path": "../legacy-system",
      "readClaudeMd": true,
      "alias": "legacy"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    // existing permissions config...
  }
}

Use Cases

1. Monorepo Development: Each service can have its own CLAUDE.md with service-specific context
2. Shared Resources: Template repositories might have CLAUDE.md files with usage instructions
3. Legacy System Reference: Include context about deprecated patterns when referencing old code
4. Third-party Libraries: Exclude CLAUDE.md from vendored dependencies that might contain irrelevant instructions
5. Team Knowledge Sharing: Shared directories can include team-specific CLAUDE.md guidelines

Expected Behavior

1. Directories specified in settings files are automatically available when Claude Code starts
2. CLAUDE.md handling:

• If readClaudeMd: true, Claude Code reads CLAUDE.md from that directory
• If readClaudeMd: false or omitted, CLAUDE.md is ignored for that directory
• Default behavior matches current --add-dir (don't read CLAUDE.md)

1. Settings hierarchy is respected:

• Project settings (.claude/settings.json) override user settings
• Local settings (.claude/settings.local.json) override both
• Enterprise managed settings take precedence over all

1. CLI --add-dir flags supplement (not replace) configured directories
2. /add-dir slash command continues to work for ad-hoc additions

Implementation Suggestions

{
  "additionalDirectories": {
    // Option 1: Mixed format support
    "paths": [
      "../backend",  // String = no CLAUDE.md
      {
        "path": "../frontend",
        "readClaudeMd": true,
        "alias": "fe",
        "description": "React frontend application"
      }
    ],
    
    // Option 2: Explicit configuration
    "directories": [
      {
        "path": "../backend",
        "readClaudeMd": false,  // explicit
        "alias": "backend",
        "description": "Main API service"
      },
      {
        "path": "~/company/design-system",
        "readClaudeMd": true,
        "alias": "design",
        "description": "Shared component library with usage guidelines"
      }
    ],
    
    // Option 3: Global default with overrides
    "defaultReadClaudeMd": false,
    "paths": [
      "../service-a",  // uses default (false)
      {"path": "../service-b", "readClaudeMd": true}  // override
    ]
  }
}

Benefits

1. Improved Developer Experience: No need to remember complex launch commands
2. Better Context Management: Precise control over which CLAUDE.md files are loaded
3. Performance: Avoid loading irrelevant CLAUDE.md files from large directory trees
4. Team Consistency: Shared project settings ensure everyone has the same directory access and context
5. Reduced Errors: Less chance of forgetting important directories or getting conflicting instructions
6. Better Documentation: Directory purposes and context handling can be documented in settings

Alternatives Considered

• Shell aliases/functions (current workaround, but not portable across team members)
• Project launch scripts (adds extra layer of indirection)
• MCP filesystem server (only for Claude Desktop, not Claude Code)
• Separate command for CLAUDE.md control (would add complexity)

Additional Context

This feature would bring Claude Code closer to feature parity with modern IDEs that support multi-root workspaces. It would be particularly valuable for enterprise teams working with complex project structures where different parts of the codebase have different contexts and guidelines.

The CLAUDE.md control is especially important because:

• Some directories might have outdated or conflicting CLAUDE.md files
• Third-party code might include irrelevant instructions
• Performance can be impacted by loading many CLAUDE.md files
• Teams need flexibility in how context is provided across different parts of their codebase

The feature could also potentially support:

• Environment variable expansion in paths ($HOME, $PROJECT_ROOT)
• Glob patterns for dynamic directory inclusion
• Read-only vs read-write directory permissions
• CLAUDE.md file precedence when multiple directories have conflicting instructions