[FEATURE] Better file discovery for multi-project workspaces (.gitignore exclusion issue)

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

## Feature Request: Better File Discovery for Monorepo/Multi-Project Setups

### Current Issue
When project folders are listed in .gitignore, the @ file reference autocomplete cannot find files in those directories. This is problematic for
configurations like:

• Shared config repository with CLAUDE.md
• Actual project code in subdirectories excluded via .gitignore
• Want Claude Code to still access these files for context

### Why This Matters (Growing Use Case)
As AI coding assistants become more capable, multi-project coordination is becoming increasingly common:

1. AI as Project Orchestrator: Users want Claude to understand and coordinate across:

• Backend services (Spring Boot, Node.js)
• Frontend applications (React, Next.js)
• Mobile apps (React Native, Swift)
• Shared infrastructure (Docker, K8s configs)

1. Centralized Context Management: Users create a "control repository" containing:

• CLAUDE.md (unified business logic and architecture)
• docs/ (cross-project documentation)
• .claude/commands/ (custom workflows)
• References to multiple project subdirectories

1. Git Organization Pattern: It's common to:

• Keep projects in .gitignore (avoid nested repos)
• Or use git submodules/worktrees
• But want Claude Code to treat them as a unified workspace

This pattern will become the norm as AI assistants handle increasingly complex, multi-service architectures.

### Current Workaround
Using additionalDirectories in .claude/settings.json helps, but:

1. Not intuitive or well-documented for this use case
2. Unclear if it fully solves the @ autocomplete issue
3. Users expect a .claudeignore file (similar to .dockerignore, .npmignore)

Priority

High (affects power users and enterprise teams significantly)

Related

File suggestion customization, workspace management, monorepo support, multi-project orchestration

Bottom Line

As AI becomes the "glue" between multiple codebases, Claude Code needs first-class support for multi-project workspaces that don't conform to traditional
monorepo structures.

Proposed Solution

Suggested Solutions

#### Option 1: Add .claudeignore support (Most intuitive)

• Separate file exclusion rules for Claude Code
• Independent from git's .gitignore
• Allows excluding node_modules, dist without affecting git
• Enables including .gitignored project folders

#### Option 2: Add setting to ignore .gitignore
```json
{
"fileSuggestion": {
"respectGitignore": false
}
}

Option 3: Enhanced additionalDirectories

• Make it clear this works with .gitignored paths
• Support glob patterns: "additionalDirectories": ["./services/*"]
• Auto-detect common patterns (submodules, worktrees)

Option 4: Better documentation

• Clarify that additionalDirectories can reference .gitignored paths
• Add examples for monorepo/multi-project setups
• Document git submodule support (if any)
• Add a "Working with Multiple Projects" guide

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

File operations

Use Case Example

Example Real-World Setup

my-platform/
├── .claude/
│ ├── settings.json
│ └── commands/
├── CLAUDE.md # Unified context for all projects
├── docs/
│ └── BUSINESS_FLOWS.md
├── backend-api/ # Actual Java project (in .gitignore)
├── web-app/ # Actual Next.js project (in .gitignore)
├── mobile-app/ # Actual React Native project (in .gitignore)
└── .gitignore # Excludes backend-api/, web-app/, mobile-app/

Users want @ to find files across ALL projects, while keeping git history separate.

Additional Context

File suggestion customization, workspace management, monorepo support, multi-project orchestration

As AI becomes the "glue" between multiple codebases, Claude Code needs first-class support for multi-project workspaces that don't conform to traditional
monorepo structures.