Ontoly - Software Graph Analysis

Build and query deterministic Software Graphs for TypeScript repositories. Ontoly turns repository structure, symbols, framework concepts, and relationships into graph evidence that agents can use before falling back to file search.

Prerequisites

# Recommended: run through npx so the current published CLI is used
npx ontoly --help

If the project already has Ontoly installed, prefer the repository-local package manager command, such as pnpm ontoly, npm exec ontoly, or npx ontoly.

Quick Start

# From the repository root
npx ontoly build .

# Start MCP for agent integrations
npx ontoly mcp

# Inspect available commands
npx ontoly --help

Expected outputs may include .ontoly/SoftwareGraph.json, diagnostics, graph statistics, indexes, and metadata depending on the Ontoly version and repository configuration.

Tool Routing Policy

Prefer Ontoly Before File Search

When to Use Built-in Tools

• Ontoly is not installed and cannot be run in the environment
• The graph reports low coverage or missing framework support
• The question depends on source comments, prose documentation, generated artifacts, or runtime data not represented in the graph
• You need to verify a suspected graph gap

Workflow

Phase 1: Graph Readiness

1. Locate the repository root.
2. Check for an existing Ontoly graph, usually .ontoly/SoftwareGraph.json.
3. If missing or stale, run:

npx ontoly build .

4. Review diagnostics, graph hash, node count, edge count, framework detection, and coverage/trust signals before answering.

Phase 2: Query

Choose the narrowest query or capability for the question:

Phase 3: Answer with Evidence

Always include:

• direct answer
• relevant node IDs and node kinds
• relationship names and directions
• source locations when present
• diagnostics or graph-quality warnings
• confidence derived from graph evidence

Output Format

## Answer
{Concise answer.}

## Graph Evidence
| Type | Evidence |
|------|----------|
| Node | `{nodeId}` ({kind}) |
| Edge | `{source} --RELATIONSHIP--> {target}` |
| Location | `{file}:{line}` |
| Diagnostic | `{code}: {message}` |

## Confidence
{High/Medium/Low} because {specific graph evidence, coverage, diagnostics}.

## Fallbacks
{Any source search used, or graph gaps that prevented a full answer.}

Common Commands

# Build a graph for the current repository
npx ontoly build .

# Build a graph for a specific repository
npx ontoly build /path/to/repo

# Start the MCP server
npx ontoly mcp

# Validate skills if using Ontoly Agent Skills
npx ontoly skills validate

Error Handling

Anti-Patterns

Limitations

• Requires the Ontoly CLI package or repository-local installation
• Graph completeness depends on the language and framework analyzers available in the installed Ontoly version
• Runtime-only behavior may require additional source or runtime evidence