File Inclusion and Exclusion Rules for Indexing Codebases in Claude Context

Claude Context recursively indexes every file under a target directory by default, while automatically excluding common VCS folders, dependency directories, and binary assets, with support for custom ignore patterns via the --ignore CLI flag.

The zilliztech/claude-context repository provides a Model Context Protocol (MCP) server that converts local codebases into searchable vector embeddings. Understanding exactly which files are ingested—and which are skipped—is critical for optimizing index size, reducing token costs, and ensuring sensitive data remains out of the vector store. The following sections detail the specific inclusion logic, built-in exclusion patterns, and extension mechanisms defined in the source code.

Default Inclusion Behavior

By default, the indexing process treats all files beneath the supplied root path as candidate documents. When you invoke the index command, the CLI receives the rootPath argument and passes it unchanged to the core synchronizer without applying any upfront filtering.

This behavior is defined in the command registration logic within packages/mcp/src/index.ts, where the index command simply accepts the directory path and delegates to the synchronization pipeline.

Built-in Exclusion Patterns

Although the walker starts with all files, it immediately applies a default ignore filter derived from the ignore utility library (a dependency of the MCP package). The following patterns are excluded automatically before any user configuration is considered:

• Version control directories: **/.git/**, **/.svn/**, **/.hg/**
• Dependency folders: **/node_modules/**
• macOS metadata: **/.DS_Store
• Image assets: **/*.png, **/*.jpg, **/*.gif, **/*.svg, **/*.ico
• Archive files: **/*.zip, **/*.tar, **/*.gz, **/*.rar

These defaults are hard-coded within the underlying ignore library and are applied inside the file walker instantiated by the synchronizer in packages/core/src/sync/synchronizer.ts.

Custom Ignore Patterns via CLI

Users can extend the default exclusion list by supplying additional glob patterns through the --ignore (or -i) command-line option. This flag accepts an array of string patterns that are appended to the internal ignore instance before the filesystem walk begins.

The option schema is explicitly declared in packages/mcp/src/index.ts at lines 140–146, where the parameter is documented as:

"Optional: Additional ignore patterns to exclude specific files/directories beyond defaults."

Example:

# Exclude build directories and log files in addition to defaults

claude-context index ./my-project \
  --ignore="build/**" \
  --ignore="*.log" \
  --ignore="private/**"

How the Filtering Pipeline Works

The inclusion and exclusion logic follows a three-stage pipeline:

1. Path Resolution: The CLI resolves the user-supplied rootPath and validates it exists.
2. Ignore Configuration: The system instantiates an ignore filter with the built-in default set, then augments it with any patterns provided via the --ignore flag (as defined in the config handling within packages/mcp/src/config.ts).
3. Filesystem Walk: The synchronizer (packages/core/src/sync/synchronizer.ts) walks the directory tree, testing each file path against the combined ignore filter. Files that match an ignore pattern are skipped; survivors are passed to the language-aware splitters in packages/core/src/splitter/ and subsequently embedded into the vector database (packages/core/src/vectordb/).

Notably, the current CLI does not expose a separate --include flag; inclusion is implicitly defined as "any file not ignored." To limit the indexed set to specific file types, you must craft negation patterns or narrow the rootPath and use --ignore to prune unwanted branches.

Key Source Files

File Path	Responsibility
packages/mcp/src/index.ts	Defines the CLI interface, including the --ignore option schema at lines 140–146.
packages/mcp/src/config.ts	Merges default configuration with user-provided ignore patterns.
packages/core/src/sync/synchronizer.ts	Executes the file walk and applies the ignore filter to the stream of paths.
packages/core/src/splitter/*	Processes only the files that pass the exclusion filter, splitting them into chunks.

Summary

• Default inclusion: All files under the target directory are candidates for indexing.
• Built-in exclusions: VCS folders (.git, .svn, .hg), node_modules, .DS_Store, images, and archives are automatically skipped by the underlying ignore library.
• Custom exclusions: Append patterns using the --ignore flag, documented in packages/mcp/src/index.ts.
• No explicit include flag: Scope control is managed exclusively through ignore patterns and careful selection of the root path.

Frequently Asked Questions

How do I prevent sensitive files like .env or credentials from being indexed?

Add them to the --ignore flag when running the index command. For example: claude-context index . --ignore=".env" --ignore="**/secrets/**". These patterns are combined with the built-in defaults, ensuring sensitive files never reach the embedding stage.

Can I index only specific file types, such as .ts and .js files?

The CLI does not provide a direct --include filter. To achieve this, you should ignore everything else using negation patterns or run the command from a subdirectory that contains only the desired file types, pruning unwanted branches with targeted --ignore entries.

Where are the default ignore patterns defined?

The default set (covering .git, node_modules, images, etc.) originates from the ignore npm package used internally. The patterns are loaded automatically when the synchronizer initializes its filter instance in packages/core/src/sync/synchronizer.ts, before any user patterns are appended.

Is there a configuration file for permanent ignore rules?

Currently, the tool does not support a standalone configuration file (such as .claudeignore). All custom exclusion patterns must be passed explicitly via the --ignore CLI argument each time the index command is executed, as implemented in the argument parser within packages/mcp/src/index.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}