OntoIndex

Graph-powered code intelligence for AI agents. OntoIndex builds a local code graph for a repository and exposes it through a CLI, an MCP server, an HTTP API, and a browser UI.

The default path is local: install, analyze, setup, connect MCP, serve, and generate wiki output against a repository you control. Browser-hosted surfaces are optional clients on top of that local graph.

Important: OntoIndex has no official cryptocurrency, token, or coin. Any token using the OntoIndex name is not affiliated with this project or its maintainers.

• Current release: 2.1.4
• Source repository: github.com/ontograph/ontoindex
• Security policy: SECURITY.md
• Enterprise contact: [email protected]
• Languages: Русский · 简体中文

Abstract

AI coding agents often work from small slices of a codebase. That is fast, but fragile: a model can edit a function without seeing callers, rename a symbol without downstream impact analysis, or miss coupling that sits outside the current prompt.

OntoIndex reduces that uncertainty by precomputing a repository graph. The graph records files, symbols, imports, calls, inheritance, routes, tools, documentation sections, communities, and execution flows. Agents can then ask graph-level questions before editing: where is this symbol used, what process does it participate in, what tests are nearby, and what changes are risky?

The index is local-first. Repository data is stored in .ontoindex/, while the global registry under ~/.ontoindex/ only tracks indexed repository metadata and paths.

What It Provides

Installation

Third-party Prerequisites

OntoIndex runs on Node.js and uses native parser packages for some languages. Install the following before installing OntoIndex.

Linux example:

node --version
npm --version
git --version
python3 --version
make --version
g++ --version

Windows PowerShell example:

node --version
npm --version
git --version
python --version
npm config get msvs_version

Install the Latest GitHub Release

Linux and macOS:

wget -qO- https://raw.githubusercontent.com/ontograph/ontoindex/master/scripts/install-ontoindex-latest.sh | bash
ontoindex --version

If wget is unavailable, curl -fsSL https://raw.githubusercontent.com/ontograph/ontoindex/master/scripts/install-ontoindex-latest.sh | bash works as a fallback.

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/ontograph/ontoindex/master/scripts/install-ontoindex-latest.ps1 | iex
ontoindex --version

Windows note:

• OntoIndex no longer supports Node.js 20 in the current release line because commander@15 requires Node.js 22.12.0 or newer.
• Node.js 24 and 25 use OntoIndex’s vendored tree-sitter runtime source, patched to compile native bindings with C++20 when prebuilds are unavailable.
• With Node.js 22 LTS, use npm 11.6.0 or newer on Windows.
• Older npm releases can bundle node-gyp builds that fail to detect Visual Studio 2026 Build Tools.
• Upgrade with npm.cmd install -g [email protected] before retrying the installer.

From a local checkout:

The installers fetch the latest GitHub release, locate the ontoindex-*.tgz asset, and install it with npm install -g. If ONTOINDEX_LOCAL_ASSET points to a tarball, or an ontoindex-*.tgz file already exists in the current directory or beside the script, the Linux/macOS installer uses that local tarball first instead of going back to GitHub. If a global install is not writable, the installers fall back to a user npm prefix.

The default installer is not an offline bundle of every third-party package. It ships OntoIndex sources and vendored parser sources, then lets npm resolve runtime dependencies such as LadybugDB, ONNX Runtime, and image/vector helpers for the current platform. A non-fatal npm deprecation warning from a transitive package can appear while upstream packages catch up. For air-gapped hosts, use an internal npm registry mirror or a prepared npm cache.

On Linux x64, the installer also prefetches LadybugDB fts and vector extension binaries from the OntoIndex GitHub extension-cache release. On Windows x64, the PowerShell installer prefetches the same binaries from the LadybugDB extension host into the local cache. At runtime, OntoIndex tries that cache before asking LadybugDB to download extensions during INSTALL fts / INSTALL VECTOR.

If a Windows install previously failed partway through and left a broken ontoindex.cmd shim, repair the global install state before retrying:

npm.cmd uninstall -g ontoindex
if (Test-Path "$env:APPDATA\npm\node_modules\ontoindex") { Remove-Item "$env:APPDATA\npm\node_modules\ontoindex" -Recurse -Force }
if (Test-Path "$env:APPDATA\npm\ontoindex.cmd") { Remove-Item "$env:APPDATA\npm\ontoindex.cmd" -Force }
if (Test-Path "$env:APPDATA\npm\ontoindex.ps1") { Remove-Item "$env:APPDATA\npm\ontoindex.ps1" -Force }

Installer configuration:

Install with npm

Use this path when npm publication is available in your environment.

Install from a Release Tarball URL

Use this when you want an immutable GitHub release asset.

First Run

Run OntoIndex from the repository you want to index. Start with the local CLI flow, then connect MCP or serve as needed; wiki generation is part of the same local workflow.

If embeddings already exist, ontoindex analyze preserves them; use ontoindex analyze --embeddings when you want to refresh semantic vectors during a rebuild.

--skills-target accepts claude, codex, cursor, opencode, or all. The default is claude, which writes generated project skills under .claude/skills/generated/; codex writes them under .agents/skills/generated/.

When the OntoIndex executable is launched from a helper checkout or global tool path, set the target repository explicitly so the MCP server cannot silently serve the wrong repository.

Linux/macOS:

cd /path/to/target/repo
export ONTOINDEX_MCP_PROJECT_CWD="$PWD"
export ONTOINDEX_MCP_REPO="$PWD"
ontoindex setup
ontoindex mcp --repo my-project

Windows PowerShell:

Set-Location C:\path\to\target\repo
$env:ONTOINDEX_MCP_PROJECT_CWD = (Get-Location).Path
$env:ONTOINDEX_MCP_REPO = (Get-Location).Path
ontoindex setup
ontoindex mcp --repo my-project

At startup, OntoIndex prints both the executable working directory and the target project path. If ONTOINDEX_MCP_REPO or --repo points outside ONTOINDEX_MCP_PROJECT_CWD, startup fails unless ONTOINDEX_MCP_ALLOW_REPO_MISMATCH=1 is set.

ontoindex mcp-doctor --repo --project-cwd --json resolves the same repo selector and reports READY, DEGRADED, or MISCONFIGURED; when it detects a mismatch, it includes a restart command for the target project scope.

MCP Client Call Shape

OntoIndex MCP tools use the client-provided namespace plus tool name. For Ontocode-style clients, the canonical call identity is:

namespace="mcp__ontoindex", name="inspect"

If a client reports unsupported call: mcp__ontoindex__inspect, the call was rejected by that client’s tool router before it reached the OntoIndex MCP server. Fix the client/router call-shape normalization or call the tool as name="inspect" with namespace="mcp__ontoindex".

MCP Setup

ontoindex setup configures supported MCP clients automatically. Manual examples are useful for debugging or for clients that do not support automatic setup.

Cursor example:

{
  "mcpServers": {
    "ontoindex": {
      "command": "ontoindex",
      "args": ["mcp"]
    }
  }
}

OpenCode example:

{
  "mcp": {
    "ontoindex": {
      "type": "local",
      "command": ["ontoindex", "mcp"]
    }
  }
}

Common Agent Workflows

Core MCP surfaces include:

Functional Architecture

OntoIndex has three entry points over the same local graph backend.

flowchart LR
  Repo[Source repository] --> Analyze[CLI analyze pipeline]
  Analyze --> Graph[.ontoindex LadybugDB graph]
  Analyze --> Registry[User registry]
  Graph --> Backend[LocalBackend]
  Registry --> Backend
  Backend --> CLI[CLI commands]
  Backend --> MCP[MCP stdio server]
  Backend --> HTTP[HTTP API]
  MCP --> Agents[AI agents and MCP clients]
  HTTP --> Web[React web UI]

Indexing Pipeline

The graph build is a typed phase DAG:

scan -> structure -> [markdown, cobol] -> parse -> [routes, tools, orm]
  -> crossFile -> mro -> communities -> processes

Key steps:

1. Scan files with repository ignore rules.
2. Parse supported languages with Tree-sitter providers.
3. Resolve imports, calls, receivers, constructors, type hints, inheritance, and method-resolution-order edges.
4. Enrich the graph with routes, MCP/RPC tools, ORM queries, markdown sections, communities, and execution flows.
5. Persist nodes and relations into LadybugDB under .ontoindex/.
6. Expose the same graph through CLI, MCP, HTTP, web UI, generated wiki pages, and generated skills.

Supported language depth varies, but the shared model covers TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, C, C++, Dart, and protobuf-related parser support.

Optional Web UI

The hosted UI is optional and can connect to a local backend at http://localhost:4747.

To run the web UI from source:

The browser-only mode can inspect uploaded ZIPs in memory. For larger repositories, start ontoindex serve and let the UI use the local index.

Docker

Images:

Comparison With Related Tools

This table compares functional scope, not benchmark speed.

Practical guidance:

• Choose OntoIndex when an agent must edit or release from local evidence: impact, diff review, docs drift, audit workflows, and target-repository safeguards.
• Choose Graphify when the main deliverable is a broad human-readable project knowledge graph across mixed artifacts.
• Choose CodeGPT Deep Graph MCP when your graph already lives in CodeGPT/DeepGraph.
• Choose smaller code-graph MCP servers when you only need AST/call/dependency lookup without a broader audit lifecycle.
• Choose Serena for language-server style symbolic edits.
• Choose Graphiti MCP for temporal memory over facts and events; it complements OntoIndex rather than replacing a source-code index.

Repository Layout

Development

Third-party development prerequisites are the same as installation, plus the package manager and compiler tools needed by native Node modules.

Useful references:

• ARCHITECTURE.md
• RUNBOOK.md
• GUARDRAILS.md
• CONTRIBUTING.md
• TESTING.md

Security and Privacy

• CLI and MCP indexing are local by default.
• Repository indexes are stored in .ontoindex/.
• The global registry stores repository paths and metadata under the user profile.
• Browser-only mode keeps uploaded code in the browser session.
• Enterprise deployments can be self-hosted.

Report security issues through SECURITY.md.

Source and Donor Acknowledgments

OntoIndex includes code originally developed as GitNexus. Copyright and attribution for GitNexus contributors are preserved in NOTICE.

The project also builds on open-source components and donated ecosystem work from upstream maintainers, including:

• Model Context Protocol
• Tree-sitter
• LadybugDB
• Graphology
• Sigma.js
• Transformers.js

See NOTICE for preserved attribution and third-party component notices.

License

OntoIndex is licensed under AGPL-3.0-or-later. See LICENSE.