Feature: Centralize and Expose File Filtering Configuration in `settings.json`

Title: Feature: Centralize and Expose File Filtering Configuration in settings.json

Labels: feature-request, enhancement, configuration, filesystem

Is your feature request related to a problem? Please describe.

Currently, Claude Code's file filtering and discovery behavior is implicit and inconsistent. While some tools like Read and Edit are documented to respect .gitignore patterns, this behavior is not consistently applied or guaranteed across all file discovery mechanisms, such as @-mention suggestions, Glob/Grep tools, and general agentic exploration of the codebase.

This creates several problems for developers:

1. Unpredictability: The logic for what files Claude Code can "see" is a black box. Users cannot be certain if .gitignore is being respected during file discovery, leading to confusion when Claude either fails to find an expected file or scans unexpected ones.
2. Lack of Control: There is no way for a user to override the default filtering. For instance, a developer might need to temporarily work on a file listed in .gitignore (like a config file or a build artifact) but cannot easily make Claude aware of it. Similarly, there is no way to add custom ignore patterns outside of .gitignore.
3. Performance and Cost: Without explicit and reliable filtering, Claude can waste time and tokens scanning large, irrelevant directories like node_modules/, dist/, or virtual environment folders. This leads to slower responses and higher API costs, as noted in the [cost documentation](/en/docs/claude-code/costs).
4. Security: Claude might inadvertently access and include sensitive information from ignored files (e.g., .env, private keys) in its context, which is a potential security risk.

Describe the solution you'd like

We propose introducing a new top-level configuration object named fileFiltering within the settings.json file. This would centralize all file discovery and filtering logic, making it transparent, predictable, and configurable.

This new configuration would apply globally to all tools and features that interact with the filesystem, including @-mention suggestions, Glob, Grep, Read, Edit, and agentic file browsing.

Here is the proposed structure for the fileFiltering object, which would live in a settings.json file (e.g., .claude/settings.json or ~/.claude/settings.json):

{
  "fileFiltering": {
    // Determines whether to respect .gitignore files found in the project.
    // Defaults to `true`. Set to `false` to have Claude see all files.
    "respectGitignore": true,

    // Determines whether to show hidden files (dotfiles) in suggestions and searches.
    // This provides an override to the typical behavior of ignoring dotfiles.
    // Defaults to `false` to reduce clutter.
    "respectHiddenFiles": false,

    // An array of glob patterns to explicitly ignore, in addition to .gitignore rules.
    // Patterns follow the .gitignore specification.
    "customIgnorePatterns": [
      "**/dist/",
      "**/*.log",
      "**/temp_*.js"
    ],

    // An array of glob patterns to explicitly include, even if they are ignored
    // by other rules. Useful for overriding broad .gitignore rules for specific files.
    "customIncludePatterns": [
      "important.log",
      "!**/dist/config.json"
    ],

    // Limits the depth of recursive file searches to prevent performance issues
    // in very large or deeply nested repositories. A value of `1` would limit
    // searches to the current directory. Set to `null` for no limit.
    "maxSearchDepth": 20
  }
}

Why this is important: Rationale & Benefits

Implementing this feature would provide significant benefits:

• Clarity & Predictability: It moves the "magic" of file filtering into an explicit, documented configuration, empowering users to understand exactly how Claude interacts with their project files.
• Performance & Cost: Reliably ignoring large directories like node_modules or build/ will drastically improve the speed and reduce the cost of many file-based operations.
• Security: It provides a robust and configurable way to ensure sensitive files are never accidentally accessed or included in Claude's context.
• Flexibility & Control: Developers gain fine-grained control over Claude's view of the filesystem. They can temporarily disable filtering to operate on an ignored file without modifying .gitignore, or add project-specific ignore rules.
• Consistency: It establishes a single, unified filtering logic that all parts of Claude Code can rely on, ensuring consistent behavior across all features.

Implementation Considerations & Affected Components

• Global Pre-Filter: The fileFiltering rules should act as a pre-filter for all filesystem operations. Files that are filtered out should not be visible to any tools or internal logic.
• Affected Components: This configuration must be respected by all tools and features that interact with the file system, including but not limited to:
• Tools: Glob, Grep, Read, Edit, Write, MultiEdit.
• Features: @-mention file and directory autocompletion.
• Internal Logic: Any agentic logic responsible for discovering files or building a file tree for context.
• Precedence: The order of precedence for filtering should be clearly defined. A recommended order is: customIncludePatterns override customIgnorePatterns, which supplement the rules from .gitignore files.
• Settings Hierarchy: This new setting should respect the existing settings precedence order documented in iam.md: enterprise > command-line > local project > shared project > user.
• Documentation: This new setting should be documented in the [Settings](/en/docs/claude-code/settings) and [Security](/en/docs/claude-code/security) pages.

Usage Examples and Scenarios

Here are several practical examples of how the fileFiltering configuration could be used to solve common developer problems.

Scenario 1: Temporarily Editing a File in .gitignore

• The Problem: Your project has a config/secrets.yml file that is in .gitignore to prevent committing sensitive keys. You need Claude's help to add a new key and refactor the file, but you don't want to remove the file from .gitignore and risk accidentally committing it.
• The Solution: You temporarily update your local settings to ignore the .gitignore rules.

``json
// In .claude/settings.local.json
{
"fileFiltering": {
"respectGitignore": false
}
}
``

• The Result: Claude can now see, read, and edit config/secrets.yml. You can ask it to "add a new API key for 'new-service' to config/secrets.yml". Once you're done, you can remove the setting or set it back to true, and your repository's .gitignore remains unchanged and safe.

---

Scenario 2: Focusing on a Single Package in a Monorepo

• The Problem: You're working in a large monorepo with many packages (/packages/api, /packages/webapp, /packages/mobile, /packages/docs). You're only working on the webapp package. File searches and @-mention suggestions are slow and cluttered with irrelevant files from other packages.
• The Solution: You use customIgnorePatterns to explicitly ignore all other packages.

``json
// In .claude/settings.local.json
{
"fileFiltering": {
"customIgnorePatterns": [
"packages/api/",
"packages/mobile/",
"packages/docs/"
]
}
}
``

• The Result: Claude's view is now focused solely on the /packages/webapp directory and root-level files. File discovery is much faster, and @-mention suggestions are highly relevant to your current task.

---

Scenario 3: Including a Specific Log File While Ignoring Others

• The Problem: Your .gitignore contains *.log to ignore all log files. However, for your current debugging task, you need Claude to analyze a specific, important log file named payment-gateway-audit.log.
• The Solution: You use customIncludePatterns to create an exception for that specific file.

``json
// In .claude/settings.json
{
"fileFiltering": {
"customIncludePatterns": [
"payment-gateway-audit.log"
]
}
}
``

• The Result: Even though all other .log files are ignored, Claude can now access payment-gateway-audit.log. You can prompt: "Analyze @payment-gateway-audit.log for any 'TRANSACTION_FAILED' errors."

---

Scenario 4: Working with Dotfiles and Environment Configuration

• The Problem: You want to use Claude to help configure your project's local development environment, which involves editing several dotfiles like .env, .nvmrc, and .vscode/launch.json. These files are often hidden from standard file discovery tools.
• The Solution: You enable respectHiddenFiles to make them visible to Claude.

``json
// In ~/.claude/settings.json (as a personal preference)
{
"fileFiltering": {
"respectHiddenFiles": true
}
}
``

• The Result: Dotfiles and directories now appear in @-mention suggestions. You can easily ask Claude to "add the DATABASE_URL from @.env to the debug configuration in @.vscode/launch.json."

---

Scenario 5: Improving Performance in a Deeply Nested Legacy Project

• The Problem: You're working on a massive legacy Java project with a directory structure that is 20+ levels deep. Simple commands like Glob or just trying to @-mention a file cause Claude to hang as it recursively scans the entire tree.
• The Solution: You limit the search depth to prevent excessive recursion.

``json
// In .claude/settings.json
{
"fileFiltering": {
"maxSearchDepth": 10
}
}
``

• The Result: File discovery operations become significantly faster. Claude's searches are now capped at 10 directories deep, providing a much better user experience while still allowing access to the most relevant files.

---

Scenario 6: Putting It All Together - A Complex Project Setup

• The Problem: You have a complex project with several requirements:

1. The entire build/ directory is in .gitignore, but you need to inspect build/asset-manifest.json.
2. The project generates temporary .tmp files that aren't in .gitignore, and you want Claude to ignore them.
3. You want to work with the project's .prettierrc configuration file.
4. The assets/ directory is huge, and you want to prevent Claude from scanning it too deeply.

• The Solution: You combine multiple fileFiltering rules.

``json
// In .claude/settings.json
{
"fileFiltering": {
"respectGitignore": true,
"respectHiddenFiles": true,
"customIgnorePatterns": [
"**/*.tmp"
],
"customIncludePatterns": [
"build/asset-manifest.json"
],
"maxSearchDepth": 5
}
}
``

• The Result: This configuration gives you fine-grained control:
• Claude respects .gitignore but makes an exception for build/asset-manifest.json.
• All temporary .tmp files are ignored.
• Hidden dotfiles like .prettierrc are visible and editable.
• Performance is maintained by limiting recursive searches to 5 levels deep.