semantic_navigate

Navigate codebases by semantic meaning instead of directory structure. Groups related files into labeled clusters using spectral clustering on embeddings to understand code organization.

Instructions

Browse the codebase by MEANING, not directory structure. Uses spectral clustering on Ollama embeddings to group semantically related files into labeled clusters. Inspired by Gabriella Gonzalez's semantic navigator. Requires Ollama running with an embedding model and a chat model for labeling.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`max_depth`	No	Maximum nesting depth of clusters. Default: 3.
`max_clusters`	No	Maximum sub-clusters per level. Default: 20.

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

Context+