# How the Ignore Filter Works in Egonex-AI to Exclude Files from Analysis

> Learn how the Egonex-AI ignore filter works. It uses a three-layer npm ignore package system to exclude files from analysis based on your configuration.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-09

---

**TLDR:** The ignore filter in Egonex-AI uses a three-layer pattern system based on the npm `ignore` package to decide which files the static-analysis pipeline should skip, checking hard-coded defaults first, then project-local configurations, with later layers able to override earlier ones via negation rules.

The **Understand Anything** repository implements a robust ignore filter to ensure its static-analysis pipeline processes only relevant source code. Located in [`packages/core/src/ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts), this filter leverages the standard `ignore` npm package to provide Git-compatible glob pattern matching. By excluding dependency folders, build artifacts, and binary assets, the system keeps the generated knowledge graph lightweight and focused on actual code.

## The Three-Layer Pattern Architecture

The `createIgnoreFilter()` function constructs rules through three ordered layers. Later layers can override earlier patterns using the `!` negation syntax supported by the underlying `ignore` library.

### Layer 1: Hard-Coded Default Patterns

The foundation consists of `DEFAULT_IGNORE_PATTERNS`, a static array defined at the top of [`ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.ts). This list includes common directories like `node_modules/`, `.git/`, `vendor/`, and `__pycache__/`, along with build outputs (`dist/`, `build/`, `.next/`), lock files ([`package-lock.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/package-lock.json), `yarn.lock`), binary assets (`*.png`, `*.mp4`), and IDE configurations (`.idea/`, `.vscode/`).

```typescript
// packages/core/src/ignore-filter.ts
export const DEFAULT_IGNORE_PATTERNS: string[] = [
  "node_modules/", ".git/", "vendor/", "venv/", "__pycache__/",
  "dist/", "build/", "out/", "coverage/", ".next/", ".cache/",
  ".turbo/", "target/", "obj/",
  "*.lock", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
  "*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg", "*.ico",
  "*.woff", "*.woff2", "*.ttf", "*.eot", "*.mp3", "*.mp4",
  "*.pdf", "*.zip", "*.tar", "*.gz",
  "*.min.js", "*.min.css", "*.map", "*.generated.*",
  ".idea/", ".vscode/",
  "LICENSE", ".gitignore", ".editorconfig", ".prettierrc",
  ".eslintrc*", "*.log",
];

```

### Layer 2: Project-Local .understandignore

The function checks for `.understand-anything/.understandignore` relative to the project root. If present, the file's raw contents are read and passed to `ig.add()`, allowing repository-specific exclusions that travel with the project.

### Layer 3: Root-Level .understandignore

Finally, the filter reads `.understandignore` directly from the project root. This provides a convenient top-level location for user-defined patterns without requiring the `.understand-anything/` directory structure.

## Filter Construction and API

The `createIgnoreFilter()` function in [`packages/core/src/ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts) orchestrates the compilation process. It instantiates the `ignore` object, adds the default patterns, then conditionally adds contents from the two possible user configuration files.

```typescript
// packages/core/src/ignore-filter.ts
export function createIgnoreFilter(projectRoot: string): IgnoreFilter {
  const ig: Ignore = ignore();

  // 1. Hard-coded defaults
  ig.add(DEFAULT_IGNORE_PATTERNS);

  // 2. .understand-anything/.understandignore
  const projectIgnorePath = join(projectRoot, ".understand-anything", ".understandignore");
  if (existsSync(projectIgnorePath)) {
    ig.add(readFileSync(projectIgnorePath, "utf-8"));
  }

  // 3. .understandignore at repository root
  const rootIgnorePath = join(projectRoot, ".understandignore");
  if (existsSync(rootIgnorePath)) {
    ig.add(readFileSync(rootIgnorePath, "utf-8"));
  }

  return {
    isIgnored(relativePath: string): boolean {
      return ig.ignores(relativePath);
    },
  };
}

```

## Integration with the Analysis Pipeline

When the **project-scanner** agent walks the filesystem, each file path is passed to the `isIgnored` method. If the method returns `true`, the file is skipped and never fed into the parser or graph builder.

This early exclusion prevents unnecessary work on large dependency folders, generated artefacts, and binary assets. The check happens before any parsing occurs, ensuring the knowledge graph remains concise and focused strictly on relevant source code.

## Overriding Default Patterns

Users can re-include specific paths that match default patterns by utilizing the `!` negation syntax in their `.understandignore` files.

Create a `.understandignore` file in your project root:

```text

# Re-include a specific package from node_modules

!node_modules/keep-me/

```

After loading this configuration, `filter.isIgnored("node_modules/keep-me/util.js")` returns `false`, allowing that specific directory to be analyzed despite the default `node_modules/` exclusion.

## Practical Implementation Examples

To use the filter programmatically:

```typescript
import { createIgnoreFilter } from "@understand-anything/core/ignore-filter";

const projectRoot = "/path/to/my/project";
const filter = createIgnoreFilter(projectRoot);

console.log(filter.isIgnored("src/index.ts"));           // false
console.log(filter.isIgnored("node_modules/lodash.js"));  // true

```

Integrating with a file walker:

```typescript
import { walk } from "some-walk-lib";
import { createIgnoreFilter } from "@understand-anything/core/ignore-filter";

const filter = createIgnoreFilter(projectRoot);
for await (const file of walk(projectRoot)) {
  const rel = file.path.slice(projectRoot.length + 1);
  if (filter.isIgnored(rel)) continue;   // Excluded here
  // Process file...
}

```

## Summary

- The ignore filter uses the npm `ignore` package to implement Git-compatible glob pattern matching in [`packages/core/src/ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts).
- **Three ordered layers** construct the filter: hard-coded defaults, `.understand-anything/.understandignore`, and root-level `.understandignore`.
- The `createIgnoreFilter()` function compiles these patterns and returns an `isIgnored()` method for runtime checks.
- Later layers override earlier ones using `!` negation syntax, allowing fine-grained control over exclusions.
- The filter prevents build artifacts, dependencies, and binary assets from entering the static-analysis pipeline, keeping the knowledge graph focused on source code.

## Frequently Asked Questions

### What configuration files does the Egonex-AI ignore filter recognize?

The filter checks for two configuration files: `.understand-anything/.understandignore` for project-local settings, and `.understandignore` at the repository root for global overrides. Both files use standard Git-ignore syntax and are processed after the hard-coded defaults but before analysis begins.

### Can I override the default ignore patterns in Understand Anything?

Yes. Create a `.understandignore` file in your project root and use the `!` negation prefix to re-include specific paths. For example, `!node_modules/special-package/` overrides the default `node_modules/` exclusion and includes that specific directory in the analysis.

### How do I programmatically check if a file is ignored?

Import `createIgnoreFilter` from `@understand-anything/core/ignore-filter` and instantiate it with your project root. The returned object provides `isIgnored(relativePath)`, which returns `true` if the file should be excluded based on the compiled three-layer rule set.

### Does the ignore filter affect analysis performance?

Yes, significantly. By excluding directories like `node_modules/` and build outputs before they reach the parser, the filter reduces memory usage and processing time. The boolean check happens early in the pipeline, ensuring irrelevant files never trigger parse operations or graph node creation.