Skip to main content
Glama

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 ontomics

Without

Tool calls

1

19

Tokens

~3.7k

~76k

Time

5s

1m 15s

Answer quality

Complete

Complete

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

With ontomics

Without

Tool calls

1

26

Tokens

~3.7k

~61.6k

Time

~5s

56s

Answer quality

Complete

Complete

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

Related MCP server: Code-Index-MCP

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):

npm install -g @ontomics/ontomics

macOS (Homebrew):

brew install EtienneChollet/tap/ontomics

Shell installer (macOS/Linux):

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

From source:

git clone https://github.com/EtienneChollet/ontomics.git
cd ontomics
cargo build --release

2. Register with your harness

Claude Code:

claude mcp add -s user ontomics -- ontomics

Codex:

codex mcp add ontomics -- ontomics

OpenClaw:

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

pi-coding-agent:

pi install npm:@ontomics/ontomics

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

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

Supported languages

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

Tools

Concepts and vocabulary

Tool

What it does

query_concept

Find all variants, related concepts, and occurrences of a term

locate_concept

Find the key signatures, classes, and files for a concept

describe_symbol

Get the signature, docstring, and relationships for a function or class

trace_concept

Trace how a concept flows through the codebase via call chains

list_concepts

List the top domain concepts by frequency

list_conventions

List all detected naming patterns (prefixes, suffixes, conversions)

list_entities

List code entities (classes, functions) filtered by concept, role, or kind

check_naming

Check an identifier against project conventions; suggests the canonical form

suggest_name

Generate an identifier name that fits the project's vocabulary

vocabulary_health

Measure convention coverage, naming consistency, and cluster cohesion

ontology_diff

Show new, changed, or removed domain concepts since a git ref

export_domain_pack

Export domain knowledge as portable YAML for use in other repos

Behavioral similarity

Tool

What it does

find_similar_logic

Find functions with behaviorally similar implementations, ranked by embedding similarity

describe_logic

Get the behavioral description, body text, and logic cluster membership for a function

compact_context

Assemble tiered context (concepts + logic) for a symbol, optimized for LLM consumption

Codebase structure

Tool

What it does

describe_file

Overview of a file's entities, concepts, and relationships

concept_map

Show which modules contain which domain concepts

type_flows

Show dominant types and how data flows through the codebase

trace_type

Trace how a specific type propagates across files and call sites

Resources

Resource

What it does

ontomics://briefing

Session 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.

Available Tools

19 tools
check_namingA

Check if an identifier follows project naming conventions — detects inconsistencies like 'n_dims' vs the project's 'ndim' convention, or 'numFeatures' vs 'nb_features'. Returns a consistent/inconsistent verdict with the canonical form and suggestions. Use before committing new code or when reviewing identifier names.

Inputs: identifier (required).

compact_contextA

Assemble minimal, token-efficient context for a concept, entity, or file — combines function body + structural summary + domain concepts + logic cluster into a compact text block suitable for LLM prompt injection. Much smaller than full source while preserving behavioral and structural information. Use when assembling context for another LLM, when asked to 'summarize X compactly', or when building prompts about codebase entities.

Inputs: scope (required), max_tokens.

concept_mapA

Semantic topology of the codebase — shows which directories concentrate which domain concepts, with entity counts and concept density. Use as a first call to understand codebase layout before drilling into specific concepts or symbols.

Inputs: no named parameters.

describe_fileA

Describe a file's structure WITHOUT reading it — returns classes, functions, and methods annotated with domain concepts and semantic roles. Use when you need to understand a file's shape, what symbols it contains, or what concepts it implements. Accepts partial paths (e.g. 'networks.py' matches 'src/networks.py'). Use describe_symbol to drill into any symbol shown.

Inputs: path (required).

describe_logicA

Describe the behavioral logic of a function or class — returns the raw function body, logic cluster membership (which other entities behave similarly), and structural centrality (PageRank importance in the dependency graph). Use when asked 'what does this function do internally', 'how does X work at a high level', or 'what is the logic of X'.

Inputs: name (required).

describe_symbolA

Describe a function or class WITHOUT reading its source file — returns signature, parameters, callers, callees, and related domain concepts. Faster and more informative than Read for understanding what a symbol does and how it fits into the codebase. Use when asked 'what does function X do' or 'what is class X'.

Inputs: name (required).

export_domain_packA

Export the project's full domain knowledge as a portable YAML pack — abbreviations, conventions, domain terms, and concept associations. Use when asked to 'export conventions', 'create a domain pack', or 'share naming rules'. The output can be reviewed, curated, and saved for use in other projects or tools.

Inputs: no named parameters.

find_similar_logicA

Find entities with similar behavioral patterns — uses logic embeddings to find functions/classes that do similar things regardless of naming. Returns similarity scores. Use when asked 'what other functions do the same thing', 'find similar implementations', or 'what behaves like X'.

Inputs: name (required), top_k.

list_conceptsA

List the project's domain vocabulary ranked by importance — a semantic overview of what this codebase is about that reading individual files cannot provide. Returns concept names as a ranked list. Use query_concept or locate_concept to drill into any result. Use when asked 'what is this project about', 'what are the main concepts', or when orienting in an unfamiliar codebase.

Inputs: top_k.

list_conventionsA

List the project's actual naming conventions detected from code — prefix patterns (nb_, is_, has_), suffix patterns, conversion patterns (x_to_y), and casing rules, each with real examples from the codebase. More accurate than guessing from a few files. Use when asked about coding style, before writing new code, or when onboarding to a project.

Inputs: no named parameters.

list_entitiesA

Find all classes and functions matching a concept — e.g. all loss functions, all network architectures, all transform utilities. Returns entity names with their domain concept tags. Use describe_symbol to drill into any result. Impossible with grep alone because it understands which functions implement a concept, not just mention it. Use when asked 'what loss functions exist', 'show me the network classes', 'what uses concept X', or 'list all X'.

Inputs: concept, role, kind, top_k.

locate_conceptA

Find the best entry points for understanding a concept — returns a ranked shortlist of key functions, classes, and files to read, plus contrastive concepts that clarify boundaries. Saves reading dozens of grep matches by surfacing the most important locations first. Use when asked 'how does X work', 'where should I look for X', or 'where are X defined'.

Inputs: term (required).

ontology_diffA

Compare the domain ontology between two git revisions — shows concepts that were added, removed, or changed. Useful for understanding how the project's vocabulary evolved across commits or for reviewing whether a PR introduced naming inconsistencies.

Inputs: since.

query_conceptA

Semantic concept lookup — returns all variants (including abbreviations like trf for transform), related concepts, naming conventions, function signatures, and file locations in one call. Richer than grep: querying 'transform' also finds 'trf', 'spatial_transform', 'apply_transform', and related concepts like 'displacement'. Use when asked 'what is X', 'what does X mean', or 'where is X used'.

Inputs: term (required), max_related, max_occurrences, max_variants, +1 more.

suggest_nameA

Generate project-consistent identifier names from a natural language description. Uses the project's actual conventions (prefixes like nb_, patterns like is_/has_, conversion patterns like x_to_y) to suggest names that fit the existing codebase style. Use when naming new functions, variables, or parameters.

Inputs: description (required).

trace_conceptA

Trace how a domain concept flows through the codebase via function call chains — shows which functions produce the concept, which consume it, and the call path between them including bridge functions on the path. Returns an ordered call chain with file locations and producer/ consumer roles. Use when asked 'how does concept X propagate', 'what calls what for X', or 'trace X through the code'.

Inputs: concept (required), max_depth.

trace_typeA

Find all data-flow edges involving a specific type. Shows which functions pass and receive this type through call edges. Use when asked 'where does Tensor flow', 'how is type X passed around', or 'which functions use type X'.

Inputs: type_name (required).

type_flowsA

Trace how types flow through the codebase along call edges. Shows which types dominate the data pipeline and how they propagate between functions. Returns all typed data-flow edges, dominant types ranked by frequency, and counts of typed vs untyped call edges.

Inputs: no named parameters.

vocabulary_healthA

Measure the vocabulary health of this codebase — returns convention coverage (how many identifiers follow conventions), consistency ratio (how uniformly concepts are spelled), and cluster cohesion (how well semantic clusters hold together). Use when asked about code quality, naming consistency, or vocabulary health. Returns an overall score plus top inconsistencies and uncovered identifiers.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 19 tools

    Disambiguation3/5

    The tools are mostly distinct in intent, but several clusters are easy to confuse: describe_file vs describe_symbol vs describe_logic, query_concept vs locate_concept vs list_concepts vs concept_map, and type_flows vs trace_type. An agent would need to read descriptions carefully to pick the right one.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern (query_concept, describe_file, trace_concept), but several use noun-ish names like type_flows, ontology_diff, concept_map, and vocabulary_health. The naming is descriptive and snake_case throughout, but the verb placement is inconsistent.

    Tool Count3/5

    19 tools is on the heavy side and there is functional overlap in the concept/type/naming clusters. However, the domain is broad enough that most tools have a distinct purpose, so the count is defensible but borderline.

    Completeness4/5

    The toolset covers file/symbol/logic description, concept queries, type flow tracing, naming-convention analysis, ontology diffing, and context generation. It's read-only and lacks direct code editing or ontology update tools, but for analysis-oriented ontology tasks it is quite complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first code indexer that provides deep code understanding for Claude and other LLMs with symbol/text search across 48+ languages, semantic search capabilities, and real-time index updates through the Model Context Protocol.
      61
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      A local-first codebase intelligence tool that enables AI assistants to research codebases using semantic search, multi-hop relationship discovery, and structural parsing. It allows users to extract architectural patterns and institutional knowledge across 30+ programming languages through an MCP-compatible interface.
      2
      741 PyPI
      1,464
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent codebase knowledge layer for AI agents. Pre-digests codebases into structured knowledge (symbols, dependency graphs, co-change patterns, architectural decisions) and serves via MCP. 28 languages, 14 tools, ~85% token reduction.
      22 npm
      10
      MIT