watthem/similar-files

Overview

This skill finds similar files in a codebase by building a TF-IDF index and ranking files with cosine similarity. First you index a workspace to produce a local index, then you run queries by file path or free text to discover related files. It is lightweight and designed for developer workflows and local code discovery.

How this skill works

The skill scans text-based files in a project and creates TF-IDF vectors for each file. For a query (a file or a text string) it computes cosine similarity between the query vector and all indexed file vectors, then returns the top matches. The index is stored locally in a .similar-files directory and can be reused for fast lookups.

When to use it

• Navigating an unfamiliar codebase to find related implementations or tests
• Refactoring: locate files that are conceptually similar before changing an API
• Code review: find other occurrences of a pattern or snippet
• Documentation: discover source files relevant to a README or design note
• Searching without relying on exact symbol or filename matches

Best practices

• Index the project root after significant file additions or removals to keep results current
• Exclude large binary or generated folders (node_modules, build outputs) before indexing
• Use --top to limit results when integrating into CI or editor tools
• Combine file-based queries and short text queries to surface both direct and conceptual matches
• Keep the .similar-files index under project control (or regenerate) to avoid stale results

Example use cases

• Run index-workspace after cloning a repository, then find-similar path/to/file.js to locate related modules
• Search by text: find-similar --text "authentication middleware" to surface files that mention or implement auth
• During a refactor, query a changed file to list other files likely affected by the same change
• When writing tests, find example tests or fixtures similar to a new feature by querying a spec file
• Integrate similar-find into an editor command to show related files alongside open buffers