fix: prevent binary/huge files from polluting LLM context when @-tagged

Return file metadata (type, size, modified date) instead of raw content
for binary files and files exceeding 512 KB, protecting context without
changing the user-facing tagging experience.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: will-lamerton

source/constants.ts

@@ -131,6 +131,62 @@ export const COST_SCORE_CHEAP = 7;
 export const COST_SCORE_MODERATE = 5;
 export const COST_SCORE_EXPENSIVE = 3;
 
+// === FILE TAGGING ===
+export const MAX_FILE_TAG_SIZE_BYTES = 512_000; // 512 KB
+export const BINARY_FILE_EXTENSIONS = new Set([
+	// Images
+	'.gif',
+	'.png',
+	'.jpg',
+	'.jpeg',
+	'.ico',
+	'.bmp',
+	'.webp',
+	'.svg',
+	'.tiff',
+	// Media
+	'.mp3',
+	'.mp4',
+	'.mov',
+	'.avi',
+	'.wav',
+	'.flac',
+	'.ogg',
+	'.webm',
+	// Archives
+	'.zip',
+	'.tar',
+	'.gz',
+	'.rar',
+	'.7z',
+	// Executables
+	'.exe',
+	'.dll',
+	'.so',
+	'.dylib',
+	'.wasm',
+	// Documents
+	'.pdf',
+	'.doc',
+	'.docx',
+	'.xls',
+	'.xlsx',
+	'.ppt',
+	'.pptx',
+	// Fonts
+	'.woff',
+	'.woff2',
+	'.ttf',
+	'.otf',
+	'.eot',
+	// Other
+	'.bin',
+	'.dat',
+	'.o',
+	'.class',
+	'.pyc',
+]);
+
 // === FILE EXPLORER ===
 export const FILE_EXPLORER_VISIBLE_ITEMS = 15;
 export const FILE_EXPLORER_TOKEN_WARNING_THRESHOLD = 10000;

source/utils/file-content-loader.spec.ts

@@ -2,6 +2,7 @@ import {mkdir, rm, writeFile} from 'node:fs/promises';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import test from 'ava';
+import {MAX_FILE_TAG_SIZE_BYTES} from '@/constants.js';
 import {loadFileContent} from './file-content-loader.js';
 
 console.log(`\nfile-content-loader.spec.ts`);
@@ -26,6 +27,13 @@ test.before(async () => {
 		'import React from "react";\n\nexport function App() {\n  return <div>Hello</div>;\n}',
 		'utf-8',
 	);
+
+	// Create a binary file (by extension)
+	await writeFile(join(testDir, 'image.gif'), Buffer.from('GIF89a'));
+
+	// Create a large text file exceeding the size limit
+	const largeContent = 'x'.repeat(MAX_FILE_TAG_SIZE_BYTES + 1);
+	await writeFile(join(testDir, 'huge.csv'), largeContent, 'utf-8');
 });
 
 test.after.always(async () => {
@@ -133,3 +141,36 @@ test('stores absolute path in metadata', async t => {
 	t.true(result.metadata.absolutePath.length >= relativePath.length);
 });
 
+test('returns metadata for binary file extensions', async t => {
+	const result = await loadFileContent(join(testDir, 'image.gif'));
+
+	t.true(result.success);
+	t.truthy(result.content);
+	t.true(result.content!.includes('[Binary file:'));
+	t.true(result.content!.includes('Type: GIF'));
+	t.true(result.content!.includes('Binary files cannot be included'));
+	t.is(result.metadata.lineCount, 0);
+});
+
+test('returns metadata for files exceeding size limit', async t => {
+	const result = await loadFileContent(join(testDir, 'huge.csv'));
+
+	t.true(result.success);
+	t.truthy(result.content);
+	t.true(result.content!.includes('[Large file:'));
+	t.true(result.content!.includes('exceeds'));
+	t.true(result.content!.includes('limit for inline tagging'));
+	t.is(result.metadata.lineCount, 0);
+});
+
+test('allows large files when line range is specified', async t => {
+	const result = await loadFileContent(join(testDir, 'huge.csv'), {
+		start: 1,
+		end: 1,
+	});
+
+	t.true(result.success);
+	// Should load the content (not metadata) since a line range was given
+	t.true(result.content!.startsWith('Path:'));
+});
+

source/utils/file-content-loader.ts

@@ -1,5 +1,6 @@
 import {readFile, stat} from 'node:fs/promises';
-import {resolve} from 'node:path';
+import {extname, resolve} from 'node:path';
+import {BINARY_FILE_EXTENSIONS, MAX_FILE_TAG_SIZE_BYTES} from '@/constants.js';
 
 interface FileContentResult {
 	success: boolean;
@@ -45,6 +46,59 @@ export async function loadFileContent(
 			};
 		}
 
+		// Binary extension check
+		const ext = extname(absPath).toLowerCase();
+		if (BINARY_FILE_EXTENSIONS.has(ext)) {
+			const fileType = ext.slice(1).toUpperCase();
+			const metadataContent = [
+				`[Binary file: ${filePath}]`,
+				`Type: ${fileType}`,
+				`Size: ${fileStats.size.toLocaleString()} bytes (${formatBytes(fileStats.size)})`,
+				`Last Modified: ${fileStats.mtime.toISOString()}`,
+				'',
+				'(Binary files cannot be included as text content)',
+			].join('\n');
+
+			return {
+				success: true,
+				content: metadataContent,
+				metadata: {
+					path: filePath,
+					absolutePath: absPath,
+					size: fileStats.size,
+					lineCount: 0,
+					lineRange,
+					tokens: Math.ceil(metadataContent.length / 4),
+				},
+			};
+		}
+
+		// Size check
+		if (fileStats.size > MAX_FILE_TAG_SIZE_BYTES && !lineRange) {
+			const estimatedLines = Math.round(fileStats.size / 40);
+			const metadataContent = [
+				`[Large file: ${filePath}]`,
+				`Size: ${fileStats.size.toLocaleString()} bytes (${formatBytes(fileStats.size)})`,
+				`Lines: ~${estimatedLines.toLocaleString()}`,
+				`Last Modified: ${fileStats.mtime.toISOString()}`,
+				'',
+				`(File exceeds ${formatBytes(MAX_FILE_TAG_SIZE_BYTES)} limit for inline tagging. Use @file:1-100 to tag specific line ranges)`,
+			].join('\n');
+
+			return {
+				success: true,
+				content: metadataContent,
+				metadata: {
+					path: filePath,
+					absolutePath: absPath,
+					size: fileStats.size,
+					lineCount: 0,
+					lineRange,
+					tokens: Math.ceil(metadataContent.length / 4),
+				},
+			};
+		}
+
 		// Read file content
 		let content: string;
 		try {
@@ -134,3 +188,9 @@ export async function loadFileContent(
 function formatFileContent(lines: string[], filePath: string): string {
 	return `Path: ${filePath}\n\n${lines.join('\n')}`;
 }
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}