File Inclusion & Exclusion Rules
Relevant source files
The following files were used as context for generating this wiki page:
File Inclusion and Exclusion rules define the boundaries of the indexing engine within the Claude Context project. These rules ensure that only relevant source code is processed into vector embeddings, optimizing performance and reducing noise in semantic search results. The system uses a combination of default hardcoded patterns, environment variable overrides, and project-specific ignore files (like .gitignore) to determine which files should be included in the vector database.
The core logic resides in the Context class, which manages supported file extensions and ignore patterns. By filtering out build artifacts, dependency directories (e.g., node_modules), and hidden version control files, the project maintains a clean and efficient search index.
Sources: packages/core/src/context.ts:1-80, packages/core/README.md:95-125
Core Filtering Logic
The Context class initializes with a set of default supported extensions and ignore patterns. These lists are merged with custom configurations provided during instantiation or through environment variables.
Supported File Extensions
The engine primarily targets source code and documentation files. By default, it supports a wide range of programming languages and markup formats.
| Category | Extensions |
|---|---|
| Programming | .ts, .tsx, .js, .jsx, .py, .java, .cpp, .c, .h, .hpp, .cs, .go, .rs, .php, .rb, .swift, .kt, .scala, .m, .mm |
| Markup & Text | .md, .markdown, .ipynb |
Sources: packages/core/src/context.ts:16-24, packages/core/README.md:143-151
Default Ignore Patterns
To prevent indexing irrelevant data, the system automatically excludes common directories and files:
- Build/Dependency:
node_modules/**,dist/**,build/**,out/**,target/**,coverage/** - Version Control:
.git/**,.svn/**,.hg/** - IDE Configs:
.vscode/**,.idea/**,*.swp,*.swo - Environment:
.env,.env.*,*.local - Minified/Bundled:
*.min.js,*.bundle.js,*.map
Sources: packages/core/src/context.ts:26-66, packages/core/README.md:153-162
Pattern Matching Architecture
The system employs a hierarchical approach to resolve which files to index. It scans for local ignore files and combines them with global rules.
The diagram shows the sequence of loading and merging patterns before applying them to specific file paths during the scanning phase.
Sources: packages/core/src/context.ts:117-156, packages/core/src/context.ts:740-780
Gitignore-style Matching Semantics
The project implements matching logic that mimics gitignore behavior, supporting:
- Wildcards: Use of
*for simple glob matching. - Directory Prefixes: Patterns ending in
/only match directories. - Negation: Patterns starting with
!un-ignore previously ignored paths. - Priority: The last matching pattern in the list takes precedence.
Sources: packages/core/src/context.ts:842-920
Configuration and Customization
Users can extend the default rules through several interfaces, including environment variables and MCP tool parameters.
Environment Variables
The following environment variables are supported for global configuration:
CUSTOM_EXTENSIONS: Comma-separated list of additional extensions to include (e.g.,.vue,.svelte).CUSTOM_IGNORE_PATTERNS: Comma-separated list of patterns to exclude.
Sources: packages/mcp/README.md:120-130, packages/core/src/context.ts:945-985
MCP Tool Parameters
When using the Model Context Protocol (MCP) server, the index_codebase tool allows for per-request customization.
| Parameter | Type | Description |
|---|---|---|
customExtensions | string[] | Additional extensions to include beyond defaults. |
ignorePatterns | string[] | Additional patterns to exclude for the current operation. |
Sources: packages/mcp/README.md:275-290, packages/mcp/CONTRIBUTING.md:55-65
File Processing Flow
During the indexCodebase operation, the Context class orchestrates the filtering logic before passing files to the CodeSplitter.
The sequence diagram illustrates how the Context class recursively traverses the directory tree while applying inclusion and exclusion filters at each step.
Sources: packages/core/src/context.ts:655-685, packages/chrome-extension/src/background.ts:250-285
Implementation Details
The filtering logic is centralized in the matchesIgnorePattern and patternMatchesPath methods. These methods normalize paths across different operating systems (handling \ vs /) to ensure consistent behavior.
// Sources: packages/core/src/context.ts:842-860
private matchesIgnorePattern(filePath: string, basePath: string, isDirectory: boolean = false): boolean {
if (this.ignorePatterns.length === 0) return false;
const relativePath = path.relative(basePath, filePath);
const normalizedPath = relativePath.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
let ignored = false;
for (const pattern of this.ignorePatterns) {
const isNegation = pattern.startsWith('!');
const actualPattern = isNegation ? pattern.slice(1) : pattern;
const matches = this.patternMatchesPath(normalizedPath, actualPattern, isDirectory);
if (matches) ignored = !isNegation;
}
return ignored;
}
The system also includes a hidden file protection mechanism where any path component starting with a dot . (e.g., .git, .env) is automatically ignored unless explicitly overridden.
Sources: packages/core/src/context.ts:850-855
Summary
File Inclusion & Exclusion Rules form the gatekeeper of the Claude Context indexing process. By combining sensible defaults for modern software development with flexible overrides via environment variables, .xxxignore files, and API parameters, the system ensures that AI agents receive high-quality, relevant code context while maintaining optimal performance on large codebases.