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: erasyuk@gmail.com
• 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

Area	Capability
Code graph	Files, folders, functions, classes, methods, interfaces, properties, routes, tools, docs sections, and process nodes
Relationships	CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, and related edges
Search	BM25, graph search, optional semantic retrieval, optional zvec vector backend, reciprocal-rank fusion, and process-grouped results
Agent safety	Impact analysis, diff-to-symbol mapping, pre-commit audit, review helpers, target test evidence, and target-repository validation
Interfaces	CLI, MCP stdio server, HTTP API, generated wiki, generated skills, and React/Vite web UI
Multi-repo work	Named repository registry, repo labels, group contracts, and cross-repo context surfaces

Installation

Third-party Prerequisites

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

Requirement	Linux	Windows
Node.js	Node.js 22.12.0 through 25.x plus npm	Node.js 22.12.0 through 25.x plus npm 11.6.0+
Git	git CLI for repository metadata and diff analysis	Git for Windows
Native build tools	python3, make, and g++ for optional native parser builds	Python 3 and Microsoft C++ Build Tools from Visual Studio Build Tools
Shell	bash for the install script examples	PowerShell 5.1 or PowerShell 7
Optional containers	Docker Engine and Docker Compose	Docker Desktop

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 npm@11.6.3 before retrying the installer.

From a local checkout:

Platform	Command
Linux/macOS	./scripts/install-ontoindex-latest.sh
Windows PowerShell	powershell -ExecutionPolicy Bypass -File .\scripts\install-ontoindex-latest.ps1

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:

Purpose	Linux/macOS	Windows PowerShell
Use another release repository	ONTOINDEX_GITHUB_REPO=owner/repo ./scripts/install-ontoindex-latest.sh	$env:ONTOINDEX_GITHUB_REPO='owner/repo'; .\scripts\install-ontoindex-latest.ps1
Use a local downloaded tarball	ONTOINDEX_LOCAL_ASSET="$PWD/ontoindex-2.1.4.tgz" ./scripts/install-ontoindex-latest.sh	—
Use a user npm prefix	ONTOINDEX_NPM_PREFIX="$HOME/.local" ./scripts/install-ontoindex-latest.sh	$env:ONTOINDEX_NPM_PREFIX="$env:APPDATA\npm"; .\scripts\install-ontoindex-latest.ps1
Force user prefix	ONTOINDEX_NPM_PREFIX="$HOME/.local" ./scripts/install-ontoindex-latest.sh	.\scripts\install-ontoindex-latest.ps1 -ForceUserPrefix
Require FTS/vector cache prefetch	ONTOINDEX_REQUIRE_LADYBUG_EXTENSIONS=1 ./scripts/install-ontoindex-latest.sh	$env:ONTOINDEX_REQUIRE_LADYBUG_EXTENSIONS='1'; .\scripts\install-ontoindex-latest.ps1
Skip FTS/vector cache prefetch	ONTOINDEX_SKIP_LADYBUG_EXTENSIONS=1 ./scripts/install-ontoindex-latest.sh	$env:ONTOINDEX_SKIP_LADYBUG_EXTENSIONS='1'; .\scripts\install-ontoindex-latest.ps1

Install with npm

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

Platform	Command
Linux/macOS	npm install -g ontoindex@2.1.4 && ontoindex --version
Windows PowerShell	npm.cmd install -g ontoindex@2.1.4; ontoindex --version

Install from a Release Tarball URL

Use this when you want an immutable GitHub release asset.

Platform	Command
Linux/macOS	npm install -g https://github.com/ontograph/ontoindex/releases/download/v2.1.4/ontoindex-2.1.4.tgz && ontoindex --version
Windows PowerShell	npm.cmd install -g https://github.com/ontograph/ontoindex/releases/download/v2.1.4/ontoindex-2.1.4.tgz; ontoindex --version

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.

Task	Linux/macOS	Windows PowerShell
Index current repository	ontoindex analyze	ontoindex analyze
Semantic query scoped to backend files	ontoindex query "search ranking" --include-path ontoindex/src/mcp/local	ontoindex query "search ranking" --include-path ontoindex/src/mcp/local
Semantic query with explanations	ontoindex query "search ranking" --include-explanations	ontoindex query "search ranking" --include-explanations
Generate repo skills for Claude and Codex	ontoindex analyze --skills --skills-target claude,codex	ontoindex analyze --skills --skills-target claude,codex
Configure supported MCP clients	ontoindex setup	ontoindex setup
Start MCP server manually	ontoindex mcp	ontoindex mcp
Diagnose MCP configuration	ontoindex mcp-doctor --repo <label-or-path> --project-cwd "$PWD" --json	ontoindex mcp-doctor --repo <label-or-path> --project-cwd "$PWD" --json
Start local HTTP backend	ontoindex serve	ontoindex serve
Generate a wiki	ontoindex wiki . --out local_docs/wiki	ontoindex wiki . --out local_docs/wiki
Check index status	ontoindex status	ontoindex status

--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 <label-or-path> --project-cwd <path> --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.

Client	Linux/macOS	Windows PowerShell
Claude Code	claude mcp add ontoindex -- ontoindex mcp	claude mcp add ontoindex -- ontoindex mcp
Codex	codex mcp add ontoindex -- ontoindex mcp	codex mcp add ontoindex -- ontoindex mcp
Ontocode	ontocode mcp add ontoindex -- ontoindex mcp	ontocode mcp add ontoindex -- ontoindex mcp
Any MCP client	command: ontoindex, args: ["mcp"]	command: ontoindex, args: ["mcp"]

Cursor example:

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

OpenCode example:

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

Common Agent Workflows

Goal	Linux/macOS	Windows PowerShell
Search for a flow	ontoindex query "authentication flow"	ontoindex query "authentication flow"
Inspect symbol context	ontoindex ctx validateUser	ontoindex ctx validateUser
Check blast radius	ontoindex impact validateUser --include-tests --depth 2	ontoindex impact validateUser --include-tests --depth 2
Review current diff	ontoindex review diff	ontoindex review diff
Audit before commit	ontoindex detect-changes	ontoindex detect-changes
Rebuild from scratch	ontoindex analyze --force	ontoindex analyze --force

Core MCP surfaces include:

Tool family	Use
Search and context	Find relevant symbols, files, routes, and processes
Impact analysis	Estimate upstream and downstream blast radius before edits
Diff review	Map changed hunks to graph symbols and execution flows
Docs evidence	Check requirements traceability, docs drift, and readiness
Refactor support	Use graph-aware rename and safety checks instead of plain find-and-replace
Systems audit	Inspect resource flow, path boundaries, error topology, concurrency, and taint-style signals

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]

Component	Path	Responsibility
CLI layer	ontoindex/src/cli/	User-facing commands such as analyze, mcp, serve, query, impact, review, docs, and audit
Ingestion pipeline	ontoindex/src/core/ingestion/	File scanning, Tree-sitter parsing, import/call/type resolution, route/tool/ORM extraction
Pipeline phases	ontoindex/src/core/ingestion/pipeline-phases/	Ordered graph build phases from scan to process extraction
Graph storage	ontoindex/src/core/lbug/	LadybugDB schema, graph loading, query execution, and embedding persistence
Registry	ontoindex/src/storage/	.ontoindex/ metadata, global registry, stale-index checks
Search	ontoindex/src/core/search/	BM25, semantic retrieval, intent routing, ranking, and repository-map context
MCP backend	ontoindex/src/mcp/	MCP resources, facade tools, gn_* workflows, and local backend dispatch
HTTP backend	ontoindex/src/server/	Express API used by the browser UI and local bridge mode
Web UI	ontoindex-web/src/	Graph explorer, repository browser, backend connection, and AI chat UI
Shared contracts	ontoindex-shared/src/	Shared API types, language identifiers, and constants

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.

Task	Linux/macOS	Windows PowerShell
Start local backend	ontoindex serve	ontoindex serve
Open hosted UI	xdg-open https://ontoindex.vercel.app	Start-Process https://ontoindex.vercel.app

To run the web UI from source:

Platform	Command
Linux/macOS	cd ontoindex-shared && npm install && npm run build && cd ../ontoindex-web && npm install && npm run dev
Windows PowerShell	Set-Location ontoindex-shared; npm install; npm run build; Set-Location ..\ontoindex-web; npm install; npm run dev

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

Task	Linux/macOS	Windows PowerShell
Start stack	docker compose up -d	docker compose up -d
Backend URL	http://localhost:4747	http://localhost:4747
Web UI URL	http://localhost:4173	http://localhost:4173

Images:

Image	Purpose
ghcr.io/ontograph/ontoindex:2.1.4	CLI, MCP server, and ontoindex serve backend
ghcr.io/ontograph/ontoindex-web:2.1.4	Web UI

Comparison With Related Tools

This table compares functional scope, not benchmark speed.

Capability	OntoIndex	GitNexus	Graphify	CodeGPT Deep Graph MCP	code-graph-mcp / Optave / CodeGraphContext	Serena	Graphiti MCP
Primary role	Local agent code-intelligence and safety layer	Historical donor and predecessor	Broad project knowledge graph and reports	MCP access to hosted CodeGPT/DeepGraph data	Lightweight local code graph servers	Symbolic code agent with memory	Temporal entity/relation memory
Local source indexing	Yes	Yes	Yes	No, hosted graph	Yes	Uses language tooling rather than the same persistent graph model	No, stores facts/events
Persistent repository graph	.ontoindex/ LadybugDB plus registry	Legacy local graph	Exported graph/report artifacts	Hosted graph	Local AST/dependency stores	Project memories and language-server state	Neo4j-backed temporal graph
MCP runtime	60+ facade and gn_* tools	Earlier concepts	Adjacent, artifact-focused	Hosted graph query tools	Search/call/impact tools	Agent tools for symbols and edits	Entity/relation memory tools
Impact analysis	Symbol, route, diff, process, test-aware signals	Partial predecessor capability	Report-oriented	Relationship queries only	Partial to strong, depending on project	Reference-based symbolic checks	Not source-code focused
Refactor safety	Graph-aware rename and verification guidance	Partial predecessor capability	No	No	Mostly analysis-oriented	Strong symbolic edits	No
Docs evidence	Requirements trace, drift checks, readiness reports	No current public successor surface	Strong mixed-document ingestion	No	Limited	Notes and memories	Memory facts, not repo docs drift
Best fit	Local editing and release workflows where agents need graph evidence before acting	Migration context	Human-readable project knowledge artifacts	Teams already using CodeGPT-hosted graphs	Smaller local AST/call graph MCP needs	Precise symbolic editing	Long-lived non-code memory

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

Path	Purpose
ontoindex/	CLI, indexing pipeline, MCP server, graph logic
ontoindex-web/	React/Vite web UI
ontoindex-shared/	Shared TypeScript types and constants
ontoindex-native/	Optional native helpers
ontoindex-claude-plugin/	Claude integration assets
ontoindex-cursor-integration/	Cursor integration assets
eval/	Evaluation harness

Development

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

Task	Linux/macOS	Windows PowerShell
Install root dependencies	npm install	npm install
Build CLI/core	cd ontoindex && npm install && npm run build	Set-Location ontoindex; npm install; npm run build
Run unit tests	cd ontoindex && npm run test:unit	Set-Location ontoindex; npm run test:unit
Type-check web UI	cd ontoindex-web && npx tsc -b --noEmit	Set-Location ontoindex-web; npx tsc -b --noEmit
Build web UI	cd ontoindex-web && npm run build	Set-Location ontoindex-web; npm run build
Run web tests	cd ontoindex-web && npm test	Set-Location ontoindex-web; npm test

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.