Context+

Instructions

Implementation Reference

• src/tools/semantic-navigate.ts:215-294 (handler)

  The main handler function for the `semantic_navigate` tool, which orchestrates file walking, analysis, embedding, clustering, and tree rendering.

  export async function semanticNavigate(options: SemanticNavigateOptions): Promise<string> {
    const maxClusters = options.maxClusters ?? 20;
    const maxDepth = options.maxDepth ?? 3;
  
    const entries = await walkDirectory({ rootDir: options.rootDir, depthLimit: 0 });
    const fileEntries = entries.filter((e) => !e.isDirectory && isNavigableSourceCandidate(e.path));
  
    if (fileEntries.length === 0) return "No supported source files found in the project.";
  
    const files: FileInfo[] = [];
    for (const entry of fileEntries) {
      try {
        const content = await readFile(entry.path, "utf-8");
        let header = extractHeader(content);
        let symbolPreview: string[] = [];
        try {
          const analysis = await analyzeFile(entry.path);
          if (analysis.header) header = analysis.header;
          symbolPreview = flattenSymbols(analysis.symbols)
            .slice(0, 3)
            .map((s) => `${s.name}@${formatLineRange(s.line, s.endLine)}`);
        } catch {
        }
        files.push({
          relativePath: entry.relativePath,
          header,
          content: content.substring(0, 500),
          symbolPreview,
        });
      } catch {
      }
    }
  
    if (files.length === 0) return "Could not read any source files.";
  
    let embeddableFiles: FileInfo[] = files;
    let vectors: number[][] = [];
    let skippedForEmbedding = 0;
    try {
      const embedded = await embedFilesWithFallback(files);
      embeddableFiles = embedded.files;
      vectors = embedded.vectors;
      skippedForEmbedding = embedded.skipped;
    } catch (err) {
      return `Ollama not available for embeddings: ${err instanceof Error ? err.message : String(err)}\nMake sure Ollama is running or signed in (ollama signin) with model ${EMBED_MODEL}.`;
    }
  
    if (embeddableFiles.length === 0) return "No embeddable source files found in the project.";
  
    if (embeddableFiles.length <= MAX_FILES_PER_LEAF) {
      let fileLabels: string[];
      try {
        const prompt = `For each file below, produce a 3-7 word description. Return ONLY a JSON array of strings.\n\n${embeddableFiles.map((f) => `${f.relativePath}: ${f.header}`).join("\n")}`;
        const response = await chatCompletion(prompt);
        const match = response.match(/\[[\s\S]*\]/);
        fileLabels = match ? JSON.parse(match[0]) : embeddableFiles.map((f) => f.header);
      } catch {
        fileLabels = embeddableFiles.map((f) => f.header);
      }
  
      const summary = skippedForEmbedding > 0
        ? `Semantic Navigator: ${embeddableFiles.length} files (${skippedForEmbedding} skipped due embedding limits)\n`
        : `Semantic Navigator: ${embeddableFiles.length} files\n`;
      const lines = [summary];
      for (let i = 0; i < embeddableFiles.length; i++) {
        const symbols = embeddableFiles[i].symbolPreview.length > 0 ? ` | symbols: ${embeddableFiles[i].symbolPreview.join(", ")}` : "";
        lines.push(`  ${embeddableFiles[i].relativePath} - ${fileLabels[i] || embeddableFiles[i].header}${symbols}`);
      }
      return lines.join("\n");
    }
  
    const tree = await buildHierarchy(embeddableFiles, vectors, maxClusters, 0, maxDepth);
    tree.label = "Project";
  
    const summary = skippedForEmbedding > 0
      ? `Semantic Navigator: ${embeddableFiles.length} files organized by meaning (${skippedForEmbedding} skipped due embedding limits)`
      : `Semantic Navigator: ${embeddableFiles.length} files organized by meaning`;
  
    return `${summary}\n\n${renderClusterTree(tree)}`;
  }

• src/tools/semantic-navigate.ts:12-16 (schema)

  Input schema for the `semantic_navigate` tool.

  export interface SemanticNavigateOptions {
    rootDir: string;
    maxDepth?: number;
    maxClusters?: number;
  }