ontomics

io.github.EtienneCholletPublished by GitHub account EtienneCholletv0.3.1Updated Nov 3, 2026

Index your codebase's domain knowledge. 20x fewer tokens, 10x faster.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper ToolsAI & ML

Overview

AI-generated overview

ontomics builds a local semantic index of a codebase's domain concepts and lets a coding agent query concepts, naming conventions, and similar logic in one…

What you can do
  • Query and locate domain concepts, list top concepts, and describe individual symbols with signatures, docstrings and relationships
  • Trace how a concept or type flows through call chains and across files
  • List detected naming conventions, check identifiers against them, suggest names, and report vocabulary health
  • Compare the domain vocabulary against a git ref and export the domain knowledge as portable YAML
  • Find functions with behaviorally similar implementations and assemble tiered context for a symbol
  • Describe files, map concepts to modules, and read a session briefing resource
When to use it
Useful when an agent needs to understand an unfamiliar or large codebase's domain vocabulary rather than just string matches or symbol definitions, and when you want fewer tool calls and tokens spent on questions like what a term means or which functions behave alike.
Requirements
Runs as a local process installed via npm (npx or global install), Homebrew, a shell installer, or from source. Needs a git repository; it refuses to index home, root or temp directories unless forced. Supported languages are Python, TypeScript, JavaScript and Rust. No API keys; embedding models are downloaded once on first run and cached, and the index is stored in the repo.
Before you install
Indexing writes an index database and config into the repository directory, and the first run downloads embedding models over the network. The shell installer pipes a remote script into a shell. The index reflects your source code, so treat the generated artifacts as sensitive if the repository is private.

Installation

In SourceWeft

  1. Open ontomics in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ontomics

[Python] [Rust] [TypeScript] [JavaScript] [platform] [MCP] [MCP Registry] [Glama] [Claude Code] [Codex] [pi]

ontomics gives any coding agent instant knowledge of your codebase. One tool call instead of 19. ~20x fewer tokens.

https://github.com/user-attachments/assets/01afa8a0-1bc2-4686-94d7-965fef7610c3

Visualization for the voxelmorph project -- a library for unsupervised learning in image registration

Benchmark

Tested with Claude Sonnet — same question, with and without ontomics.

"What does 'transform' mean in this codebase?" on voxelmorph (full transcript):

With ontomicsWithout
Tool calls119
Tokens~3.7k~76k
Time5s1m 15s
Answer qualityCompleteComplete

"What are the main domain concepts in this codebase?" on ScribblePrompt (full transcript):

With ontomicsWithout
Tool calls126
Tokens~3.7k~61.6k
Time~5s56s
Answer qualityCompleteComplete

Both conditions produced complete, correct answers. ontomics got there in one call.

What it does that search can't

Search tells you where a string appears. An LSP tells you where a symbol is defined and referenced. Neither answers: what are the domain concepts in this codebase? How do they relate? What naming conventions emerged? What changed in the domain vocabulary since last release? Which functions behave similarly, regardless of what they're named?

ontomics builds a semantic index of your project's domain — clustering related symbols into concepts, detecting naming conventions from usage frequency, resolving abbreviations, grouping functions by behavioral similarity, and tracking how the vocabulary evolves over time. That index can be exported as a portable artifact to bootstrap conventions in other repos.

Behavioral similarity

Beyond naming and concepts, ontomics embeds raw function bodies using CodeRankEmbed (768-dim, contrastive code retrieval) and clusters them by behavioral similarity. This surfaces relationships that neither naming nor call graphs expose:

❯ What functions behave like spatial_transform()?
  random_transform()   nn/functional.py:352   0.80  spatial_transform()  functional.py:596      0.69  random_transform()   functional.py:1399     0.67  random_disp()        nn/functional.py:275   0.65  integrate_disp()     functional.py:764      0.65  compose()            nn/functional.py:216   0.63  disp_to_trf()        functional.py:343      0.62

The result also reveals that random_transform appears at two locations with different similarity scores — a sign of implementation duplication that concept-level search would miss entirely.

Install

Install once, available in every project. No configuration needed — ontomics auto-detects the repo and indexes it on first run.

ontomics requires a git repository (.git/ directory). It will refuse to index home, root, or temp directories. To index a non-git directory, pass --force.

1. Install the binary

npm (macOS/Linux):

bash
npm install -g @ontomics/ontomics

macOS (Homebrew):

bash
brew install EtienneChollet/tap/ontomics

Shell installer (macOS/Linux):

bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/EtienneChollet/ontomics/releases/latest/download/ontomics-installer.sh | sh

From source:

bash
git clone https://github.com/EtienneChollet/ontomics.gitcd ontomicscargo build --release

2. Register with your harness

Claude Code:

bash
claude mcp add -s user ontomics -- ontomics

Codex:

bash
codex mcp add ontomics -- ontomics

OpenClaw:

bash
openclaw mcp set ontomics '{"command":"ontomics"}'

pi-coding-agent:

bash
pi install npm:@ontomics/ontomics

Share with your team — drop an .mcp.json in your repo root:

json
{  "mcpServers": {    "ontomics": {      "command": "npx",      "args": ["-y", "@ontomics/ontomics", "--repo", "."]    }  }}

Supported languages

Python, TypeScript, JavaScript, Rust. Auto-detected from file extensions.

Tools

Concepts and vocabulary

ToolWhat it does
query_conceptFind all variants, related concepts, and occurrences of a term
locate_conceptFind the key signatures, classes, and files for a concept
describe_symbolGet the signature, docstring, and relationships for a function or class
trace_conceptTrace how a concept flows through the codebase via call chains
list_conceptsList the top domain concepts by frequency
list_conventionsList all detected naming patterns (prefixes, suffixes, conversions)
list_entitiesList code entities (classes, functions) filtered by concept, role, or kind
check_namingCheck an identifier against project conventions; suggests the canonical form
suggest_nameGenerate an identifier name that fits the project's vocabulary
vocabulary_healthMeasure convention coverage, naming consistency, and cluster cohesion
ontology_diffShow new, changed, or removed domain concepts since a git ref
export_domain_packExport domain knowledge as portable YAML for use in other repos

Behavioral similarity

ToolWhat it does
find_similar_logicFind functions with behaviorally similar implementations, ranked by embedding similarity
describe_logicGet the behavioral description, body text, and logic cluster membership for a function
compact_contextAssemble tiered context (concepts + logic) for a symbol, optimized for LLM consumption

Codebase structure

ToolWhat it does
describe_fileOverview of a file's entities, concepts, and relationships
concept_mapShow which modules contain which domain concepts
type_flowsShow dominant types and how data flows through the codebase
trace_typeTrace how a specific type propagates across files and call sites

Resources

ResourceWhat it does
ontomics://briefingSession briefing: top conventions, abbreviations, key concepts, contrastive pairs, and vocabulary warnings. Also available via ontomics briefing CLI.

How it works

ontomics runs a multi-stage pipeline entirely on your machine — no API keys required:

  1. Parse — tree-sitter extracts every identifier, signature, and call site from your source files
  2. Analyze — TF-IDF scoring identifies domain-specific concepts and detects naming conventions
  3. Embed (concepts) — BGE-small (384-dim) clusters related concepts by semantic similarity
  4. Embed (logic) — CodeRankEmbed (768-dim) embeds raw function bodies and clusters them by behavioral similarity
  5. Centrality — PageRank scores entities by structural importance

Both embedding models are downloaded once on first run and cached locally. The index lives at <repo>/.ontomics/index.db — subsequent startups load from cache and watch for file changes.

Configuration via .ontomics/config.toml in the repo root. All fields have sensible defaults. See SPEC.md for the full design contract.

Source: README.md at commit 897a953

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts