# File Inclusion and Exclusion Rules for Indexing Codebases in Claude Context

> Discover Claude Context's file inclusion and exclusion rules for indexing codebases. Learn how to customize index patterns and optimize your codebase analysis with default and custom ignore flags.

- Repository: [Zilliz/claude-context](https://github.com/zilliztech/claude-context)
- Tags: how-to-guide
- Published: 2026-04-22

---

**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`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/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:**

```bash

# 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`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/config.ts)).
3. **Filesystem Walk**: The synchronizer ([`packages/core/src/sync/synchronizer.ts`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/index.ts) | Defines the CLI interface, including the `--ignore` option schema at lines 140–146. |
| [`packages/mcp/src/config.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/config.ts) | Merges default configuration with user-provided ignore patterns. |
| [`packages/core/src/sync/synchronizer.ts`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/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`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/index.ts).