ontomics is a semantic indexing tool that provides coding agents with domain knowledge about a codebase. Its goal is not to replace search or LSP, but to answer questions that search and LSP cannot answer: what domain concepts exist in this codebase, how they relate to each other, what naming conventions have formed, what has changed in the domain vocabulary since the last version, and which functions are behaviorally similar (regardless of naming). According to the official description, with ontomics, coding agents can replace 19 calls with a single tool call, reduce token consumption by about 20 times, and shorten agent search time by about 10 times.
Main capabilities ontomics builds a semantic index for a project's domain: it clusters related symbols into concepts, detects naming conventions based on usage frequency, resolves abbreviations, groups functions by behavioral similarity, and tracks vocabulary changes over time. The index can be exported as a portable artifact for bootstrapping conventions in other repositories.
For behavioral similarity, ontomics uses CodeRankEmbed (768-dimensional, contrastive code retrieval) to embed raw function bodies and clusters them by behavioral similarity. This can reveal relationships that neither naming nor the call graph can expose, for example the same function appearing in two places with different similarity scores, suggesting possible implementation duplication.
How to use ontomics can be installed once and used across all projects with no configuration: on first run it automatically detects the repository and builds the index. It requires the target to be a git repository (with a .git/ directory present), and will refuse to index the home, root, or temporary directories; to index a non-git directory, you can pass --force.
Ways to install the binary include: npm (macOS/Linux), macOS (Homebrew), and the Shell installer (macOS/Linux). Ways to register it with a harness include pi-coding-agent; for team sharing, you can place .mcp.json in the repository root.
Supported languages Python, TypeScript, JavaScript, Rust, automatically detected based on file extension.
How it works ontomics runs a fully local multi-stage pipeline with no API key required:
- Parse: tree-sitter extracts every identifier, signature, and call site from source files
- Analyze: TF-IDF scoring identifies domain-specific concepts and detects naming conventions
- Embed (concepts): BGE-small (384 dimensions) clusters related concepts by semantic similarity
- Embed (logic): CodeRankEmbed (768 dimensions) embeds raw function bodies and clusters them by behavioral similarity
- Centrality: PageRank scores entities by structural importance
The two embedding models are downloaded once on first run and cached locally. The index is located at <repo>/.ontomics/index.db, and subsequent startups load from the cache and watch for file changes. Configuration is done through .ontomics/config.toml in the repository root, all fields have reasonable defaults, and the complete design conventions are in SPEC.md.
Use cases and limitations ontomics is suitable for scenarios where coding agents need to quickly understand a codebase's domain concepts, naming conventions, and vocabulary evolution, and is also suitable for reusing conventions across multiple repositories. Its limitations include: it requires a git repository (non-git directories require --force), and it currently supports only four languages: Python, TypeScript, JavaScript, and Rust; more information such as pricing, cost, and platform support scope is not yet available in the materials.
