opencode-context 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,38 @@
 # opencode-context
 
-Smart file finder for codebases with relevance scoring. Includes an OpenCode plugin.
+Semantic code search with ranked file matches and contextual line snippets showing exactly where matches occur. Available as CLI and OpenCode plugin.
+
+---
+
+## Quick Reference for AI Agents
+
+**Tool:** `find_files`  
+**Purpose:** Find relevant files before reading them  
+**When to use:** User asks to find, locate, search, or "where is X"
+
+### Arguments
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | **YES** | - | What to find (e.g., "auth", "database models") |
+| maxFiles | number | no | 5 | Number of results |
+| minScore | number | no | 15 | Relevance threshold (0-100) |
+| includeTests | boolean | no | false | Include *.test.*, *.spec.* |
+| includeConfigs | boolean | no | false | Include *.config.*, .rc files |
+| includeDocs | boolean | no | false | Include *.md, docs/ |
+
+### Examples
+
+```
+find_files query="authentication middleware"
+find_files query="database" maxFiles=10 includeTests=true
+find_files query="config" includeConfigs=true
+```
+
+**Scoring:** Filename (highest) > Path > Content > Imports/Exports  
+**Tip:** If no results, try `minScore=5` for broader search
+
+---
 
 ## Installation
 
@@ -65,11 +97,14 @@ The plugin registers the `find_files` tool.
 | `includeTests` | boolean | false | Include test files |
 | `includeConfigs` | boolean | false | Include config files |
 | `includeDocs` | boolean | false | Include documentation |
+| `includeLinePreviews` | boolean | false | Show matching line snippets |
+| `maxSnippetsPerFile` | number | 3 | Max line snippets per file |
 
 **Example:**
 
 ```
 find_files query="auth middleware" maxFiles=5
+find_files query="database" includeLinePreviews=true maxSnippetsPerFile=5
 ```
 
 **Scoring algorithm considers:**
@@ -101,15 +136,17 @@ opencode-context -q "database" --json
 | `-j, --json` | JSON output | false |
 | `-d, --detailed` | Show match reasons | false |
 | `-i, --interactive` | Interactive mode | false |
+| `--line-previews` | Show matching line snippets | false |
+| `--max-snippets` | Max snippets per file | 3 |
 
 ## How It Works
 
 1. Scans directory with fast-glob
-2. Extracts metadata (size, language, exports, imports)
+2. Extracts metadata (size, language, exports, imports, **line index**)
 3. Scores each file against query
-4. Returns ranked results
+4. Returns ranked results with optional line-level previews
 
-No index persistence - scans fresh on each query.
+No index persistence - scans fresh on each query. Line previews show the exact context where matches occur, with surrounding lines for full context.
 
 ## Uninstallation
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA4M1C,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiQ1C,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/index.js

@@ -7960,6 +7960,61 @@ var DOC_PATTERNS = [
 ];
 
 // src/search.ts
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-zA-Z0-9_]+/).filter((w2) => w2.length > 2);
+}
+function buildLineIndex(lines) {
+  const index = new Map;
+  lines.forEach((line, idx) => {
+    const terms = tokenize(line);
+    terms.forEach((term) => {
+      if (!index.has(term)) {
+        index.set(term, []);
+      }
+      index.get(term).push(idx + 1);
+    });
+  });
+  return index;
+}
+function extractLineSnippets(content, lineIndex, query, maxSnippets = 3) {
+  const matchedLines = new Set;
+  for (const term of [...query.terms, ...query.exactTerms]) {
+    const positions = lineIndex.get(term.toLowerCase());
+    if (positions) {
+      positions.forEach((lineNum) => matchedLines.add(lineNum));
+    }
+  }
+  if (matchedLines.size === 0) {
+    return [];
+  }
+  const lines = content.split(`
+`);
+  const sortedLines = Array.from(matchedLines).sort((a2, b2) => a2 - b2);
+  const clusters = [];
+  let currentCluster = [sortedLines[0]];
+  for (let i = 1;i < sortedLines.length; i++) {
+    if (sortedLines[i] - sortedLines[i - 1] <= 3) {
+      currentCluster.push(sortedLines[i]);
+    } else {
+      clusters.push(currentCluster);
+      currentCluster = [sortedLines[i]];
+    }
+  }
+  clusters.push(currentCluster);
+  const topClusters = clusters.sort((a2, b2) => b2.length - a2.length).slice(0, maxSnippets);
+  return topClusters.map((cluster) => {
+    const centerLine = cluster[Math.floor(cluster.length / 2)];
+    const lineIdx = centerLine - 1;
+    return {
+      lineNumber: centerLine,
+      content: lines[lineIdx]?.trim() || "",
+      context: {
+        before: lines.slice(Math.max(0, lineIdx - 1), lineIdx).map((l2) => l2.trim()),
+        after: lines.slice(lineIdx + 1, Math.min(lines.length, lineIdx + 2)).map((l2) => l2.trim())
+      }
+    };
+  });
+}
 function parseQuery(query) {
   if (!query || typeof query !== "string") {
     return {
@@ -8043,7 +8098,7 @@ function detectLanguage(filePath) {
   }
   return;
 }
-async function extractMetadata(filePath) {
+async function extractMetadata(filePath, includeLineIndex = false) {
   const stats = await fs.stat(filePath);
   const content = await fs.readFile(filePath, "utf-8").catch(() => "");
   const lines = content.split(`
@@ -8058,7 +8113,9 @@ async function extractMetadata(filePath) {
     isDoc: isDocFile(filePath),
     language: detectLanguage(filePath),
     exports: extractExports(content),
-    imports: extractImports(content)
+    imports: extractImports(content),
+    lineIndex: includeLineIndex ? buildLineIndex(lines) : undefined,
+    content: includeLineIndex ? content : undefined
   };
 }
 function extractExports(content) {
@@ -8165,33 +8222,39 @@ function calculateFilepathScore(filePath, query) {
   }
   return { score: totalScore, reasons };
 }
-async function calculateContentScore(filePath, query, content) {
+async function calculateContentScore(filePath, query, metadata, maxSnippets) {
   const reasons = [];
   let totalScore = 0;
-  const fileContent = content ?? await fs.readFile(filePath, "utf-8").catch(() => "");
+  const fileContent = metadata?.content ?? await fs.readFile(filePath, "utf-8").catch(() => "");
   const normalizedContent = fileContent.toLowerCase();
-  const lines = fileContent.split(`
-`);
   for (const term of query.terms) {
     const occurrences = (normalizedContent.match(new RegExp(term, "g")) || []).length;
     if (occurrences > 0) {
       const contribution = Math.min(DEFAULT_WEIGHTS.content, DEFAULT_WEIGHTS.content * (occurrences / 5));
       totalScore += contribution;
-      reasons.push({
+      const reason = {
         type: "content",
         description: `Content contains "${term}" (${occurrences} occurrences)`,
         contribution
-      });
+      };
+      if (metadata?.lineIndex && metadata.content && maxSnippets && maxSnippets > 0) {
+        reason.lineSnippets = extractLineSnippets(metadata.content, metadata.lineIndex, query, maxSnippets);
+      }
+      reasons.push(reason);
     }
   }
   for (const exact of query.exactTerms) {
     if (normalizedContent.includes(exact.toLowerCase())) {
       totalScore += DEFAULT_WEIGHTS.content * 1.5;
-      reasons.push({
+      const reason = {
         type: "content",
         description: `Exact phrase in content: "${exact}"`,
         contribution: DEFAULT_WEIGHTS.content * 1.5
-      });
+      };
+      if (metadata?.lineIndex && metadata.content && maxSnippets && maxSnippets > 0) {
+        reason.lineSnippets = extractLineSnippets(metadata.content, metadata.lineIndex, query, maxSnippets);
+      }
+      reasons.push(reason);
     }
   }
   for (const term of query.terms) {
@@ -8279,14 +8342,14 @@ function calculateMetadataScore(metadata, query) {
   }
   return { score: totalScore, reasons };
 }
-async function calculateFileScore(filePath, query, metadata, rootPath, searchContent) {
+async function calculateFileScore(filePath, query, metadata, rootPath, searchContent, maxSnippets) {
   const relativePath = relative(rootPath, filePath);
   const filenameResult = calculateFilenameScore(filePath, query);
   const filepathResult = calculateFilepathScore(filePath, query);
   const metadataResult = calculateMetadataScore(metadata, query);
   let contentResult = { score: 0, reasons: [] };
   if (searchContent && metadata.size < 1024 * 1024) {
-    contentResult = await calculateContentScore(filePath, query);
+    contentResult = await calculateContentScore(filePath, query, metadata, maxSnippets);
   }
   const totalScore = Math.min(100, filenameResult.score + filepathResult.score + metadataResult.score + contentResult.score);
   const allReasons = [
@@ -8312,6 +8375,8 @@ async function searchFiles(options) {
   const minScore = options.minScore || 15;
   const searchContent = options.searchContent ?? true;
   const maxFileSize = options.maxFileSize || 1024 * 1024;
+  const includeLinePreviews = options.includeLinePreviews ?? false;
+  const maxSnippetsPerFile = options.maxSnippetsPerFile || 3;
   const excludePatterns = [
     ...DEFAULT_EXCLUDE_PATTERNS,
     ...options.exclude || []
@@ -8338,8 +8403,8 @@ async function searchFiles(options) {
       const stats = await fs.stat(filePath);
       if (stats.size > maxFileSize)
         continue;
-      const metadata = await extractMetadata(filePath);
-      const match = await calculateFileScore(filePath, parsedQuery, metadata, rootPath, searchContent);
+      const metadata = await extractMetadata(filePath, includeLinePreviews);
+      const match = await calculateFileScore(filePath, parsedQuery, metadata, rootPath, searchContent, includeLinePreviews ? maxSnippetsPerFile : 0);
       if (match.score >= minScore) {
         matches.push(match);
       }
@@ -8371,7 +8436,25 @@ function formatFileSize(bytes) {
     return `${(bytes / 1024).toFixed(1)}KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
-function formatResults(result, detailed = false) {
+function formatLineSnippet(snippet, maxWidth = 80) {
+  const lines = [];
+  const separator = import_picocolors3.default.gray("│");
+  snippet.context.before.forEach((line, idx) => {
+    const lineNum = snippet.lineNumber - snippet.context.before.length + idx;
+    const trimmed = line.slice(0, maxWidth - 10);
+    lines.push(`        ${import_picocolors3.default.gray(String(lineNum).padStart(4))} ${separator} ${import_picocolors3.default.gray(trimmed)}`);
+  });
+  const mainLine = snippet.content.slice(0, maxWidth - 10);
+  lines.push(`        ${import_picocolors3.default.cyan(String(snippet.lineNumber).padStart(4))} ${separator} ${mainLine}`);
+  snippet.context.after.forEach((line, idx) => {
+    const lineNum = snippet.lineNumber + 1 + idx;
+    const trimmed = line.slice(0, maxWidth - 10);
+    lines.push(`        ${import_picocolors3.default.gray(String(lineNum).padStart(4))} ${separator} ${import_picocolors3.default.gray(trimmed)}`);
+  });
+  return lines.join(`
+`);
+}
+function formatResults(result, detailed = false, showLinePreviews = false) {
   console.log("");
   if (result.files.length === 0) {
     console.log(import_picocolors3.default.yellow("No matching files found."));
@@ -8390,8 +8473,17 @@ function formatResults(result, detailed = false) {
       for (const reason of file.reasons) {
         const icon = reason.type === "filename" ? "\uD83D\uDCDD" : reason.type === "filepath" ? "\uD83D\uDCC1" : reason.type === "content" ? "\uD83D\uDCC4" : reason.type === "function" ? "⚡" : reason.type === "class" ? "\uD83C\uDFD7️" : reason.type === "export" ? "↗️" : reason.type === "test" ? "\uD83E\uDDEA" : reason.type === "config" ? "⚙️" : "•";
         console.log(`        ${icon} ${import_picocolors3.default.gray(reason.description)}`);
+        if (showLinePreviews && reason.lineSnippets && reason.lineSnippets.length > 0) {
+          console.log("");
+          for (const snippet of reason.lineSnippets) {
+            console.log(formatLineSnippet(snippet));
+          }
+          console.log("");
+        }
+      }
+      if (!showLinePreviews || !file.reasons.some((r2) => r2.lineSnippets && r2.lineSnippets.length > 0)) {
+        console.log("");
       }
-      console.log("");
     }
   }
 }
@@ -8444,6 +8536,14 @@ async function interactiveMode() {
     fe(import_picocolors3.default.yellow("Cancelled"));
     process.exit(0);
   }
+  const showLinePreviews = await me({
+    message: "Show matching line snippets?",
+    initialValue: false
+  });
+  if (BD(showLinePreviews)) {
+    fe(import_picocolors3.default.yellow("Cancelled"));
+    process.exit(0);
+  }
   const s = L2();
   s.start("Searching...");
   try {
@@ -8453,11 +8553,13 @@ async function interactiveMode() {
       includeTests: includeType === "all" || includeType === "tests",
       includeConfigs: includeType === "all" || includeType === "configs",
       includeDocs: includeType === "all",
-      searchContent: true
+      searchContent: true,
+      includeLinePreviews: showLinePreviews,
+      maxSnippetsPerFile: 3
     };
     const result = await searchFiles(options);
     s.stop(`Search complete`);
-    formatResults(result, detailed);
+    formatResults(result, detailed, showLinePreviews);
     fe(import_picocolors3.default.green(`Found ${result.files.length} files`));
   } catch (error) {
     s.stop("Search failed");
@@ -8468,8 +8570,8 @@ async function interactiveMode() {
 }
 function runCLI() {
   const program2 = new Command;
-  program2.name("opencode-context").description("Smart file finder for codebases - semantic search with confidence scoring").version("1.0.3");
-  program2.option("-q, --query <query>", "Search query").option("-n, --max-files <number>", "Maximum number of results", "5").option("--min-score <score>", "Minimum relevance score (0-100)", "15").option("-p, --path <path>", "Root path to search from", process.cwd()).option("--include-tests", "Include test files", false).option("--include-configs", "Include configuration files", false).option("--include-docs", "Include documentation files", false).option("--no-content", "Skip content search (faster)").option("--max-size <bytes>", "Maximum file size to read", "1048576").option("-j, --json", "Output as JSON", false).option("-d, --detailed", "Show detailed match reasons", false).option("-i, --interactive", "Interactive mode", false).action(async (options) => {
+  program2.name("opencode-context").description("Semantic code search with ranked file matches and contextual line snippets").version("1.0.8");
+  program2.option("-q, --query <query>", "Search query").option("-n, --max-files <number>", "Maximum number of results", "5").option("--min-score <score>", "Minimum relevance score (0-100)", "15").option("-p, --path <path>", "Root path to search from", process.cwd()).option("--include-tests", "Include test files", false).option("--include-configs", "Include configuration files", false).option("--include-docs", "Include documentation files", false).option("--no-content", "Skip content search (faster)").option("--max-size <bytes>", "Maximum file size to read", "1048576").option("--line-previews", "Show matching line snippets", false).option("--max-snippets <number>", "Maximum snippets per file", "3").option("-j, --json", "Output as JSON", false).option("-d, --detailed", "Show detailed match reasons", false).option("-i, --interactive", "Interactive mode", false).action(async (options) => {
     try {
       if (options.interactive || !options.query) {
         await interactiveMode();
@@ -8484,13 +8586,15 @@ function runCLI() {
         includeConfigs: options.includeConfigs,
         includeDocs: options.includeDocs,
         searchContent: options.content !== false,
-        maxFileSize: parseInt(options.maxSize, 10)
+        maxFileSize: parseInt(options.maxSize, 10),
+        includeLinePreviews: options.linePreviews,
+        maxSnippetsPerFile: parseInt(options.maxSnippets, 10)
       };
       const result = await searchFiles(searchOptions);
       if (options.json) {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        formatResults(result, options.detailed);
+        formatResults(result, options.detailed, options.linePreviews);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);

package/dist/install.d.ts

@@ -1,3 +1,5 @@
 #!/usr/bin/env bun
-export {};
+declare function updateAgentsMd(): Promise<void>;
+declare function updateOpencodeConfig(): Promise<void>;
+export { updateAgentsMd, updateOpencodeConfig };
 //# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":""}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":";AAuGA,iBAAe,cAAc,kBAyB5B;AAED,iBAAe,oBAAoB,kBA+BlC;AAwBD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/install.js

@@ -4,7 +4,9 @@
 // src/install.ts
 import { promises as fs } from "fs";
 import { join, dirname } from "path";
-var CONFIG_PATH = join(process.env.HOME || "", ".config/opencode/opencode.json");
+import { homedir } from "os";
+var CONFIG_PATH = join(process.env.HOME || homedir(), ".config/opencode/opencode.json");
+var AGENTS_PATH = join(process.env.HOME || homedir(), ".config/opencode/AGENTS.md");
 async function ensureConfigDir() {
   const dir = dirname(CONFIG_PATH);
   try {
@@ -25,31 +27,136 @@ async function writeConfig(config) {
   await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + `
 `);
 }
-async function install() {
-  console.log(`Installing opencode-context plugin...
-`);
-  await ensureConfigDir();
+async function readAgentsMd() {
+  try {
+    return await fs.readFile(AGENTS_PATH, "utf-8");
+  } catch {
+    return "";
+  }
+}
+async function writeAgentsMd(content) {
+  await fs.writeFile(AGENTS_PATH, content);
+}
+var TOOL_DOCUMENTATION = `
+## find_files Tool (opencode-context plugin)
+
+**Purpose:** Semantic file search for locating relevant code files before reading them.
+
+**When to use:**
+- User asks to find, locate, or search for files
+- Before reading multiple files to understand a codebase
+- Looking for specific functionality (auth, database, config, etc.)
+- User mentions "where is X defined" or "find Y"
+
+**Arguments:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | YES | - | Search query describing what to find (e.g., "auth middleware", "user model") |
+| maxFiles | number | NO | 5 | Maximum number of files to return |
+| minScore | number | NO | 15 | Minimum relevance score (0-100). Lower = more results |
+| includeTests | boolean | NO | false | Include test files (*.test.*, *.spec.*, etc.) |
+| includeConfigs | boolean | NO | false | Include configuration files (*.config.*, .rc files) |
+| includeDocs | boolean | NO | false | Include documentation (*.md, README, docs/) |
+
+**Usage examples:**
+
+\`\`\`
+# Basic search
+find_files query="authentication"
+
+# More results with tests
+find_files query="database" maxFiles=10 includeTests=true
+
+# Find config files
+find_files query="webpack" includeConfigs=true
+
+# Low threshold for broader search
+find_files query="utils" minScore=5
+\`\`\`
+
+**Scoring algorithm:**
+- Filename matches (highest weight)
+- Directory path matches
+- Content matches (function names, class names)
+- Import/export statements
+- File type (tests ranked lower unless requested)
+
+**Best practices:**
+1. Call this BEFORE reading files when user asks to find something
+2. Use maxFiles=10+ when doing initial codebase exploration
+3. Set includeTests=true only when user specifically asks about tests
+4. If no results, try lowering minScore to 5 or using broader terms
+5. Results include relevance scores - files above 50 are highly relevant
+`;
+async function updateAgentsMd() {
+  const existingContent = await readAgentsMd();
+  const toolMarker = "## find_files Tool (opencode-context plugin)";
+  if (existingContent.includes(toolMarker)) {
+    const beforeTool = existingContent.split(toolMarker)[0];
+    const afterTool = existingContent.split(toolMarker)[1];
+    const nextHeading = afterTool.search(/\n## /);
+    const rest = nextHeading >= 0 ? afterTool.slice(nextHeading) : "";
+    const newContent = beforeTool + TOOL_DOCUMENTATION + `
+` + rest;
+    await writeAgentsMd(newContent);
+    console.log("\u2713 Updated AGENTS.md with find_files documentation");
+  } else {
+    const header = existingContent.includes("# Available Tools") ? existingContent : existingContent.trim() ? existingContent + `
+
+# Available Tools
+` : `# Available Tools
+`;
+    const newContent = header + `
+` + TOOL_DOCUMENTATION;
+    await writeAgentsMd(newContent);
+    console.log("\u2713 Created/updated AGENTS.md with find_files documentation");
+  }
+}
+async function updateOpencodeConfig() {
   const config = await readConfig();
   if (!config.plugin) {
     config.plugin = [];
   }
   const pluginName = "opencode-context@latest";
-  if (config.plugin.includes(pluginName)) {
-    console.log("\u2713 opencode-context already in plugins");
-  } else {
+  if (!config.plugin.includes(pluginName)) {
     config.plugin.push(pluginName);
     console.log("\u2713 Added opencode-context@latest to plugins");
+  } else {
+    console.log("\u2713 opencode-context already in plugins");
+  }
+  if (!config.instructions) {
+    config.instructions = [];
+  }
+  const agentsRef = "~/.config/opencode/AGENTS.md";
+  if (!config.instructions.includes(agentsRef)) {
+    config.instructions.push(agentsRef);
+    console.log("\u2713 Added AGENTS.md to instructions");
+  } else {
+    console.log("\u2713 AGENTS.md already in instructions");
   }
   await writeConfig(config);
+}
+async function install() {
+  console.log(`Installing opencode-context plugin...
+`);
+  await ensureConfigDir();
+  await updateOpencodeConfig();
+  await updateAgentsMd();
   console.log(`
 \u2713 Installation complete!`);
   console.log(`
 To use:`);
-  console.log("  1. Run opencode in your project");
-  console.log('  2. Ask: "Find files related to auth"');
-  console.log(`  3. The agent will use find_files tool
+  console.log("  1. Restart opencode if running");
+  console.log("  2. The AI agent will now see find_files in available tools");
+  console.log(`  3. Try: "Find files related to authentication"
 `);
 }
-if (__require.main == __require.module) {
+var isMainModule = process.argv[1]?.includes("install.js") || process.argv[1]?.includes("install.ts");
+if (isMainModule) {
   install().catch(console.error);
 }
+export {
+  updateOpencodeConfig,
+  updateAgentsMd
+};

package/dist/plugin.js

@@ -17706,6 +17706,61 @@ var DOC_PATTERNS = [
 ];
 
 // src/search.ts
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-zA-Z0-9_]+/).filter((w) => w.length > 2);
+}
+function buildLineIndex(lines) {
+  const index = new Map;
+  lines.forEach((line, idx) => {
+    const terms = tokenize(line);
+    terms.forEach((term) => {
+      if (!index.has(term)) {
+        index.set(term, []);
+      }
+      index.get(term).push(idx + 1);
+    });
+  });
+  return index;
+}
+function extractLineSnippets(content, lineIndex, query, maxSnippets = 3) {
+  const matchedLines = new Set;
+  for (const term of [...query.terms, ...query.exactTerms]) {
+    const positions = lineIndex.get(term.toLowerCase());
+    if (positions) {
+      positions.forEach((lineNum) => matchedLines.add(lineNum));
+    }
+  }
+  if (matchedLines.size === 0) {
+    return [];
+  }
+  const lines = content.split(`
+`);
+  const sortedLines = Array.from(matchedLines).sort((a, b) => a - b);
+  const clusters = [];
+  let currentCluster = [sortedLines[0]];
+  for (let i = 1;i < sortedLines.length; i++) {
+    if (sortedLines[i] - sortedLines[i - 1] <= 3) {
+      currentCluster.push(sortedLines[i]);
+    } else {
+      clusters.push(currentCluster);
+      currentCluster = [sortedLines[i]];
+    }
+  }
+  clusters.push(currentCluster);
+  const topClusters = clusters.sort((a, b) => b.length - a.length).slice(0, maxSnippets);
+  return topClusters.map((cluster) => {
+    const centerLine = cluster[Math.floor(cluster.length / 2)];
+    const lineIdx = centerLine - 1;
+    return {
+      lineNumber: centerLine,
+      content: lines[lineIdx]?.trim() || "",
+      context: {
+        before: lines.slice(Math.max(0, lineIdx - 1), lineIdx).map((l) => l.trim()),
+        after: lines.slice(lineIdx + 1, Math.min(lines.length, lineIdx + 2)).map((l) => l.trim())
+      }
+    };
+  });
+}
 function parseQuery(query) {
   if (!query || typeof query !== "string") {
     return {
@@ -17789,7 +17844,7 @@ function detectLanguage(filePath) {
   }
   return;
 }
-async function extractMetadata(filePath) {
+async function extractMetadata(filePath, includeLineIndex = false) {
   const stats = await fs.stat(filePath);
   const content = await fs.readFile(filePath, "utf-8").catch(() => "");
   const lines = content.split(`
@@ -17804,7 +17859,9 @@ async function extractMetadata(filePath) {
     isDoc: isDocFile(filePath),
     language: detectLanguage(filePath),
     exports: extractExports(content),
-    imports: extractImports(content)
+    imports: extractImports(content),
+    lineIndex: includeLineIndex ? buildLineIndex(lines) : undefined,
+    content: includeLineIndex ? content : undefined
   };
 }
 function extractExports(content) {
@@ -17911,33 +17968,39 @@ function calculateFilepathScore(filePath, query) {
   }
   return { score: totalScore, reasons };
 }
-async function calculateContentScore(filePath, query, content) {
+async function calculateContentScore(filePath, query, metadata, maxSnippets) {
   const reasons = [];
   let totalScore = 0;
-  const fileContent = content ?? await fs.readFile(filePath, "utf-8").catch(() => "");
+  const fileContent = metadata?.content ?? await fs.readFile(filePath, "utf-8").catch(() => "");
   const normalizedContent = fileContent.toLowerCase();
-  const lines = fileContent.split(`
-`);
   for (const term of query.terms) {
     const occurrences = (normalizedContent.match(new RegExp(term, "g")) || []).length;
     if (occurrences > 0) {
       const contribution = Math.min(DEFAULT_WEIGHTS.content, DEFAULT_WEIGHTS.content * (occurrences / 5));
       totalScore += contribution;
-      reasons.push({
+      const reason = {
         type: "content",
         description: `Content contains "${term}" (${occurrences} occurrences)`,
         contribution
-      });
+      };
+      if (metadata?.lineIndex && metadata.content && maxSnippets && maxSnippets > 0) {
+        reason.lineSnippets = extractLineSnippets(metadata.content, metadata.lineIndex, query, maxSnippets);
+      }
+      reasons.push(reason);
     }
   }
   for (const exact of query.exactTerms) {
     if (normalizedContent.includes(exact.toLowerCase())) {
       totalScore += DEFAULT_WEIGHTS.content * 1.5;
-      reasons.push({
+      const reason = {
         type: "content",
         description: `Exact phrase in content: "${exact}"`,
         contribution: DEFAULT_WEIGHTS.content * 1.5
-      });
+      };
+      if (metadata?.lineIndex && metadata.content && maxSnippets && maxSnippets > 0) {
+        reason.lineSnippets = extractLineSnippets(metadata.content, metadata.lineIndex, query, maxSnippets);
+      }
+      reasons.push(reason);
     }
   }
   for (const term of query.terms) {
@@ -18025,14 +18088,14 @@ function calculateMetadataScore(metadata, query) {
   }
   return { score: totalScore, reasons };
 }
-async function calculateFileScore(filePath, query, metadata, rootPath, searchContent) {
+async function calculateFileScore(filePath, query, metadata, rootPath, searchContent, maxSnippets) {
   const relativePath = relative(rootPath, filePath);
   const filenameResult = calculateFilenameScore(filePath, query);
   const filepathResult = calculateFilepathScore(filePath, query);
   const metadataResult = calculateMetadataScore(metadata, query);
   let contentResult = { score: 0, reasons: [] };
   if (searchContent && metadata.size < 1024 * 1024) {
-    contentResult = await calculateContentScore(filePath, query);
+    contentResult = await calculateContentScore(filePath, query, metadata, maxSnippets);
   }
   const totalScore = Math.min(100, filenameResult.score + filepathResult.score + metadataResult.score + contentResult.score);
   const allReasons = [
@@ -18058,6 +18121,8 @@ async function searchFiles(options) {
   const minScore = options.minScore || 15;
   const searchContent = options.searchContent ?? true;
   const maxFileSize = options.maxFileSize || 1024 * 1024;
+  const includeLinePreviews = options.includeLinePreviews ?? false;
+  const maxSnippetsPerFile = options.maxSnippetsPerFile || 3;
   const excludePatterns = [
     ...DEFAULT_EXCLUDE_PATTERNS,
     ...options.exclude || []
@@ -18084,8 +18149,8 @@ async function searchFiles(options) {
       const stats = await fs.stat(filePath);
       if (stats.size > maxFileSize)
         continue;
-      const metadata = await extractMetadata(filePath);
-      const match = await calculateFileScore(filePath, parsedQuery, metadata, rootPath, searchContent);
+      const metadata = await extractMetadata(filePath, includeLinePreviews);
+      const match = await calculateFileScore(filePath, parsedQuery, metadata, rootPath, searchContent, includeLinePreviews ? maxSnippetsPerFile : 0);
       if (match.score >= minScore) {
         matches.push(match);
       }

package/dist/search.d.ts

@@ -4,7 +4,7 @@ export declare function isTestFile(filePath: string): boolean;
 export declare function isConfigFile(filePath: string): boolean;
 export declare function isDocFile(filePath: string): boolean;
 export declare function detectLanguage(filePath: string): string | undefined;
-export declare function extractMetadata(filePath: string): Promise<FileMetadata>;
-export declare function calculateFileScore(filePath: string, query: ParsedQuery, metadata: FileMetadata, rootPath: string, searchContent: boolean): Promise<FileMatch>;
+export declare function extractMetadata(filePath: string, includeLineIndex?: boolean): Promise<FileMetadata>;
+export declare function calculateFileScore(filePath: string, query: ParsedQuery, metadata: FileMetadata, rootPath: string, searchContent: boolean, maxSnippets?: number): Promise<FileMatch>;
 export declare function searchFiles(options: SearchOptions): Promise<SearchResult>;
 //# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EAET,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EAOZ,MAAM,YAAY,CAAC;AAEpB,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA+DrD;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQnE;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiB7E;AAgQD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC,SAAS,CAAC,CAmCpB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAiE/E"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EAET,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EAQZ,MAAM,YAAY,CAAC;AAkFpB,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA+DrD;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQnE;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,gBAAgB,GAAE,OAAe,GAChC,OAAO,CAAC,YAAY,CAAC,CAmBvB;AAgRD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,OAAO,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,CAAC,CAmCpB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAoE/E"}

package/dist/types.d.ts

@@ -10,8 +10,17 @@ export interface MatchReason {
     description: string;
     matchedContent?: string;
     contribution: number;
+    lineSnippets?: LineSnippet[];
 }
 export type MatchType = 'filename' | 'filepath' | 'content' | 'export' | 'import' | 'function' | 'class' | 'interface' | 'comment' | 'config' | 'test' | 'related';
+export interface LineSnippet {
+    lineNumber: number;
+    content: string;
+    context: {
+        before: string[];
+        after: string[];
+    };
+}
 export interface FileMetadata {
     size: number;
     lastModified: Date;
@@ -23,6 +32,8 @@ export interface FileMetadata {
     language?: string;
     exports?: string[];
     imports?: string[];
+    lineIndex?: Map<string, number[]>;
+    content?: string;
 }
 export interface SearchOptions {
     query: string;
@@ -36,6 +47,8 @@ export interface SearchOptions {
     includeDocs?: boolean;
     searchContent?: boolean;
     maxFileSize?: number;
+    includeLinePreviews?: boolean;
+    maxSnippetsPerFile?: number;
 }
 export interface SearchResult {
     files: FileMatch[];

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-context",
-  "version": "1.0.6",
-  "description": "Smart file finder for codebases - semantic search with confidence scoring. Also available as an OpenCode plugin.",
+  "version": "1.0.8",
+  "description": "Semantic code search with ranked file matches and contextual line snippets showing exactly where matches occur. Available as CLI and OpenCode plugin.",
   "type": "module",
   "main": "./dist/plugin.js",
   "exports": {
@@ -14,13 +14,15 @@
   "files": [
     "dist/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "plugin.json"
   ],
   "scripts": {
     "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node && bun build ./src/install.ts --outfile ./dist/install.js --target node && echo '#!/usr/bin/env node' | cat - ./dist/index.js > temp && mv temp ./dist/index.js && chmod +x ./dist/index.js",
     "build:types": "tsc --emitDeclarationOnly",
     "dev": "bun run src/index.ts",
     "test": "bun test",
+    "postinstall": "node dist/install.js || echo 'Run: bunx opencode-context@latest install'",
     "prepublishOnly": "bun run build && bun run build:types"
   },
   "dependencies": {

package/plugin.json

@@ -0,0 +1,87 @@
+{
+  "name": "opencode-context",
+  "version": "1.0.6",
+  "description": "Smart file finder for codebases with semantic search and relevance scoring",
+  "main": "dist/plugin.js",
+  "tools": [
+    {
+      "name": "find_files",
+      "description": "Find relevant files in the codebase based on a semantic search query. Use this to locate files related to a task before reading them. Returns ranked results with relevance scores.",
+      "whenToUse": [
+        "User asks to find, locate, or search for files",
+        "Before reading multiple files to understand a codebase",
+        "Looking for specific functionality (auth, database, config, etc.)",
+        "User mentions 'where is X defined' or 'find Y'"
+      ],
+      "args": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Search query describing what to find (e.g., 'auth middleware', 'user model')"
+        },
+        "maxFiles": {
+          "type": "number",
+          "required": false,
+          "default": 5,
+          "description": "Maximum number of files to return"
+        },
+        "minScore": {
+          "type": "number",
+          "required": false,
+          "default": 15,
+          "description": "Minimum relevance score (0-100). Lower = more results"
+        },
+        "includeTests": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include test files (*.test.*, *.spec.*, etc.)"
+        },
+        "includeConfigs": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include configuration files (*.config.*, .rc files)"
+        },
+        "includeDocs": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include documentation (*.md, README, docs/)"
+        }
+      },
+      "examples": [
+        {
+          "description": "Basic search",
+          "usage": "find_files query='authentication'"
+        },
+        {
+          "description": "More results with tests",
+          "usage": "find_files query='database' maxFiles=10 includeTests=true"
+        },
+        {
+          "description": "Find config files",
+          "usage": "find_files query='webpack' includeConfigs=true"
+        },
+        {
+          "description": "Low threshold for broader search",
+          "usage": "find_files query='utils' minScore=5"
+        }
+      ],
+      "bestPractices": [
+        "Call this BEFORE reading files when user asks to find something",
+        "Use maxFiles=10+ when doing initial codebase exploration",
+        "Set includeTests=true only when user specifically asks about tests",
+        "If no results, try lowering minScore to 5 or using broader terms",
+        "Results include relevance scores - files above 50 are highly relevant"
+      ],
+      "scoringFactors": [
+        "Filename matches (highest weight)",
+        "Directory path matches",
+        "Content matches (function names, class names)",
+        "Import/export statements",
+        "File type (tests ranked lower unless requested)"
+      ]
+    }
+  ]
+}