# How to Configure Custom File Extensions for Claude Context: 3 Proven Methods

> Learn 3 ways to configure custom file extensions for Claude Context including environment variables commands and VS Code filters Expand your codebase indexing beyond defaults

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

---

**Set the `CUSTOM_EXTENSIONS` environment variable, pass `customExtensions` to the MCP `index_codebase` command, or use the VS Code search filter to include non-standard file types in your codebase indexing.**

Claude Context discovers source files using a **whitelist of supported extensions** defined in the core engine. By default, it ships with an extensive list covering common languages—`.ts`, `.py`, `.java`, `.go`, `.rs`, and many more—specified in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts) at lines 26-34. When your project uses frameworks or languages outside this default set, you need to configure custom file extensions for Claude Context to index them properly.

## Why Default Extensions Aren't Enough

Modern development stacks frequently include file types that fall outside standard language extensions. Vue single-file components (`.vue`), Svelte files (`.svelte`), Astro templates (`.astro`), or even custom DSL formats need explicit whitelisting. The Claude Context engine implements three distinct mechanisms to handle these cases, each suited to different workflows and deployment scenarios.

## Method 1: Environment Variable for Global Configuration

The simplest approach uses the `CUSTOM_EXTENSIONS` environment variable, parsed automatically when a `Context` instance initializes. This method works across CLI usage, MCP server deployments, and programmatic integrations.

### How It Works

The `getCustomExtensionsFromEnv()` function at lines 1118-1129 in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts) reads the variable, splits on commas, and normalizes each entry to ensure a leading dot. These extensions merge with and extend the default whitelist.

### Implementation

```bash

# Shell export (add to ~/.bashrc, ~/.zshrc, or session)

export CUSTOM_EXTENSIONS=".vue,.svelte,.astro"

# Or in a .env file loaded by your application

echo 'CUSTOM_EXTENSIONS=".vue,.svelte,.astro"' > .env

```

After setting this variable, any new `Context` instance automatically includes these extensions:

```typescript
import { Context } from '@zilliz/claude-context-core';

// CUSTOM_EXTENSIONS env var is read automatically during construction
const ctx = new Context();
await ctx.indexCodebase('/my/project'); // Indexes .vue, .svelte, .astro files

```

### Best For

- **Development environments** where you control the shell configuration
- **Docker deployments** where environment variables are easily injected
- **CI/CD pipelines** requiring consistent extension sets across runs

## Method 2: MCP Command Parameter for Runtime Flexibility

When using Claude Context through the Model Context Protocol (MCP) server, you can pass `customExtensions` directly in the `index_codebase` command payload. This provides per-request customization without environment changes.

### How It Works

The handler in [`packages/mcp/src/handlers.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/handlers.ts) (lines 46-50) extracts the `customExtensions` array from the JSON-RPC request, normalizes entries by ensuring leading dots, and invokes `Context.addCustomExtensions()` before triggering the indexing operation.

### Implementation

```json
POST /mcp/index_codebase
Content-Type: application/json

{
  "path": "/home/user/my-astro-project",
  "customExtensions": [".vue", "svelte", "astro"],
  "force": false,
  "splitter": "ast"
}

```

Note that the leading dot is optional in the array—`"svelte"` and `".svelte"` both normalize correctly to `.svelte`.

### Programmatic MCP Client Example

```typescript
import { Client } from '@modelcontextprotocol/sdk';

const client = new Client({ transport: new StdioTransport() });

await client.request({
  method: 'index_codebase',
  params: {
    path: '/my/project',
    customExtensions: ['.vue', '.svelte', '.astro'],
    force: true
  }
});

```

### Best For

- **Multi-tenant MCP servers** serving diverse project types
- **IDE integrations** where projects have varying extension needs
- **Ad-hoc indexing** without persistent configuration changes

## Method 3: VS Code Search Filter for Query Scoping

The VS Code extension offers a search interface that accepts extension filters. Importantly, this method **does not modify the indexing whitelist**—it only narrows search results to files with specified extensions that were already indexed through other means.

### How It Works

The [`searchCommand.ts`](https://github.com/zilliztech/claude-context/blob/main/searchCommand.ts) file (lines 64-88) in `packages/vscode-extension/src/commands/` prompts the user for optional extensions, validates the input format, and constructs a Milvus filter expression: `fileExtension in ['.vue', '.svelte', '.astro']`. This filter applies to the semantic search query.

### Implementation

1. Open the Command Palette (`⇧⌘P` / `Ctrl+Shift+P`)
2. Select **Claude Context: Search**
3. Enter your query (e.g., "authentication middleware")
4. When prompted *"Optional: filter by file extensions"*, enter:

```

.vue,.svelte,.astro

```

The search will return only results from files matching these extensions.

### Combining with Custom Indexing

To actually search custom extensions, you must first ensure they're indexed:

```bash

# Terminal - set extensions before starting VS Code

export CUSTOM_EXTENSIONS=".vue,.svelte,.astro"
code .

```

Then use the search filter to scope results.

### Best For

- **Targeted exploration** of large polyglot codebases
- **Framework-specific queries** (e.g., "find all Vue composables")
- **Search result refinement** without re-indexing

## Method Comparison: Choosing the Right Approach

| Method | Modifies Indexing? | Persistence | Best Use Case |
|--------|-------------------|-------------|---------------|
| `CUSTOM_EXTENSIONS` env var | **Yes** | Session/persistent | Development workstations, CI/CD |
| MCP `customExtensions` parameter | **Yes** | Per-request | MCP servers, IDE plugins |
| VS Code search filter | **No** | Per-query | Result filtering, exploration |

## Programmatic Configuration Deep Dive

For Node.js/TypeScript applications using the core library directly, the `Context` constructor accepts configuration options that merge with environment and default settings.

```typescript
import { Context } from '@zilliz/claude-context-core';

// Method A: Pass customExtensions in constructor config
const ctx = new Context({
  customExtensions: ['.vue', '.svelte', '.astro']
});

// Method B: Or use supportedExtensions to completely override defaults
const ctx = new Context({
  supportedExtensions: ['.py', '.vue', '.svelte'] // Only these three
});

```

The constructor processing sequence in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts) follows this priority:

1. `DEFAULT_SUPPORTED_EXTENSIONS` (hardcoded defaults)
2. `config.supportedExtensions` (complete override, if provided)
3. `config.customExtensions` (additive merge)
4. `CUSTOM_EXTENSIONS` environment variable (additive merge)
5. Deduplication via `new Set(allSupportedExtensions)`

## Summary

- **Claude Context uses a whitelist approach** for file discovery, with extensive defaults in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts)
- **Three methods extend the whitelist**: `CUSTOM_EXTENSIONS` environment variable, MCP `customExtensions` parameter, and VS Code search filters (query-only)
- **Environment variables provide persistent configuration** for development environments and CI/CD pipelines
- **MCP parameters enable runtime flexibility** for multi-tenant servers and IDE integrations
- **Programmatic configuration** via `Context` constructor options allows complete customization in embedded applications

## Frequently Asked Questions

### What file extensions does Claude Context support by default?

Claude Context ships with a comprehensive whitelist covering mainstream programming languages. The default list in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts) (lines 26-34) includes `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.java`, `.go`, `.rs`, `.cpp`, `.c`, `.h`, `.hpp`, `.rb`, `.php`, `.scala`, `.kt`, `.swift`, `.r`, `.m`, `.mm`, `.cs`, `.pas`, `.dart`, `.elm`, `.erl`, `.ex`, `.exs`, `.fs`, `.fsx`, `.groovy`, `.hs`, `.jl`, `.lua`, `.ml`, `.mli`, `.nim`, `.nims`, `.ml`, `.pl`, `.pm`, `.pony`, `.pro`, `.purs`, `.rkt`, `.scm`, `.ss`, `.st`, `.tcl`, `.v`, `.vhd`, `.vhdl`, `.zig`, and various configuration formats like `.json`, `.yaml`, `.yml`, `.toml`, `.xml`, `.sql`, `.md`, `.rst`, `.dockerfile`, `.makefile`, `.cmake`, `.gradle`, `.sbt`, `.ini`, `.cfg`, `.conf`, `.properties`, `.env`, `.sh`, `.bash`, `.zsh`, `.fish`, `.ps1`, `.bat`, `.cmd`.

### Can I use custom extensions without a leading dot?

Yes. Claude Context normalizes extension inputs automatically. The `addCustomExtensions` method in [`packages/core/src/context.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/context.ts) (lines 65-78) ensures every entry starts with a leading dot before adding it to the whitelist. This means both `"vue"` and `".vue"` resolve to `.vue` correctly.

### Why doesn't the VS Code search filter add extensions to the index?

The VS Code search filter operates at query time, not indexing time. As implemented in [`packages/vscode-extension/src/commands/searchCommand.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/commands/searchCommand.ts) (lines 64-88), it constructs a Milvus `fileExtension in [...]` filter expression to scope results from already-indexed files. To actually index new extension types, you must use the `CUSTOM_EXTENSIONS` environment variable or MCP `customExtensions` parameter before indexing runs.