[BUG] @ file mention excludes all Python (.py) files but shows .md, .yaml, .ipynb files

Summary

In Claude Code, the @ file mention autocomplete feature completely excludes all Python (.py) files from the suggestion list while successfully showing other file types (.md, .yaml, .ipynb, .json). This makes it impossible to reference Python source files using the @ autocomplete feature in Python projects.

Environment

• Claude Code Version: [Current version - 2025]
• Platform: VS Code Devcontainer (Docker)
• OS: Linux (devcontainer)
• Project Type: Large Python web application project
• Project Size: ~900MB, ~26,000 files

Detailed File Statistics

| File Type | Count | Appears in @ Mention? |
|-----------|-------|----------------------|
| Python (.py) | 568 | ❌ NO (completely excluded) |
| Markdown (.md) | 378 | ✅ YES |
| YAML (.yaml/.yml) | 42 | ✅ YES |
| Jupyter (.ipynb) | 95 | ✅ YES |
| JSON (.json) | 79 | ✅ YES (some) |

Reproduction Steps

1. Open a large Python project (25K+ files, 568 .py files)
2. In Claude Code chat, type @ to trigger file mention autocomplete
3. Observe the file picker popup
4. Try searching for any Python file (e.g., type "agent", "main", "service", "__init__")
5. Result: Zero Python files appear in the suggestions
6. Expected: Python files should appear alongside other file types

Specific Examples

Files that should appear but don't:

src/agents/main_agent.py (39KB, 933 lines - main application file)
src/app/main.py (application entry point)
src/services/core_service.py (core business logic)
src/models/data_model.py (data models)

Files that do appear:

CLAUDE.md
README.md
docker-compose.yml
*.ipynb notebooks

Impact

High Impact for Python Developers:

1. Cannot use @ autocomplete for the primary language of the project (Python)
2. Discoverability: Users cannot browse available Python modules/files
3. Workflow disruption: Must remember exact file paths or use alternative discovery methods
4. Inconsistent UX: Works for documentation files but not source code
5. Forces workarounds: Users must type full paths manually without autocomplete assistance

Workarounds Used

Since @ mention doesn't work for .py files, users must:

1. Type full file paths manually: "Check src/agents/main_agent.py"
2. Use Glob tool: "Find Python files matching *agent*"
3. Use Grep tool: "Search for 'class MainAgent' in Python files"
4. Read/Edit tools still work with full paths (only @ autocomplete is affected)

Root Cause Analysis

Based on investigation and related issues:

1. File filtering is hardcoded and non-configurable (per Issue #4904)
2. Claude Code appears to prioritize certain file types in large projects:

• Documentation files (.md) → indexed
• Config files (.yaml, .json) → indexed
• Notebooks (.ipynb) → indexed
• Source code (.py, .js, .ts) → excluded (likely performance optimization)

1. No configuration exists to control this behavior:

• No .claudeignore equivalent
• .claude/settings.local.json only has permissions
• No file filtering options in settings

Related Issues

• #4904 - "Feature: Centralize and Expose File Filtering Configuration"
• Confirms file filtering is "implicit and inconsistent"
• Requests configurable fileFiltering settings
• This issue would be solved by implementing #4904

• #5182 - "Missing File Discovery with @ After Migration and Update"
• Reports missing files in @ mention

• #2012 - "File Reference Autocomplete Broken"
• General @ autocomplete issues

• #2315 - "File Path Mention Inconsistency"
• Erratic file results

Expected Behavior

Option A (Ideal):

• All file types should appear in @ mention by default
• Large projects: intelligent sampling or lazy loading instead of complete exclusion
• Show most recently accessed/modified files first

Option B (Configurable):

• Implement Issue #4904's fileFiltering configuration
• Allow users to control which file types to index
• Example:

``json
{
"fileFiltering": {
"includePatterns": ["**/*.py", "**/*.md", "**/*.yaml"],
"excludePatterns": ["**/*.pyc", "**/__pycache__/**"],
"maxFilesPerType": 1000
}
}
``

Option C (Performance-aware):

• Index up to N files per file type (e.g., 1000 .py files, 500 .md files)
• Show warning: "Showing first 1000 Python files, use Glob for full search"
• Allow users to increase limits

Additional Context

Project Structure:

my-project/
├── src/
│   ├── app/          # Web application (want @ mention)
│   ├── services/     # Business logic (want @ mention)
│   ├── models/       # Data models (want @ mention)
│   ├── agents/       # Agent modules (want @ mention)
│   ├── core/         # Core functionality (want @ mention)
│   └── utils/        # Utilities (want @ mention)
├── tests/            # Test files (want @ mention)
├── docs/             # Documentation (already works ✅)
└── scripts/          # Utility scripts (want @ mention)

Configuration checked:

• ✅ Python files are NOT in .gitignore
• ✅ No .claudeignore file exists
• ✅ Files have normal permissions (644)
• ✅ Files are valid UTF-8 Python source
• ✅ VS Code file exclusions don't affect Claude Code indexing

Request

Please either:

1. Fix the file type filtering to include .py files in large projects
2. Implement Issue #4904 to make file filtering configurable
3. Document the current behavior so users know which file types are excluded and why
4. Provide temporary workaround or flag to force .py file indexing

This significantly impacts Python developers using Claude Code, as they cannot use @ mention for their primary development files.