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

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 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 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

# 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:

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 (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

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

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 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:

# 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.

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 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
• 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 (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 (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 (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.

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