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
| Task |
Avoid |
Use Ontoly |
| Architecture summary |
Reading every README/source folder |
Build graph, inspect graph statistics and architecture report |
| Impact analysis |
Grep for identifier text |
Query dependencies, callers, callees, and related nodes |
| Request flow |
Manually follow controller/service files |
Trace route/controller/service relationships |
| Configuration audit |
Search .env names only |
Query configuration and environment-variable nodes |
| Dead code review |
Guess from unused exports |
Use graph diagnostics and unreachable/dead-code evidence |
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
- Locate the repository root.
- Check for an existing Ontoly graph, usually
.ontoly/SoftwareGraph.json.
- If missing or stale, run:
npx ontoly build .
- 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:
| Question Type |
Query Direction |
| "What owns auth?" |
Services, controllers, modules, packages |
| "What handles POST /login?" |
Routes, handlers, request lifecycle |
| "What breaks if I remove X?" |
Impact analysis, consumers, dependency traversal |
| "Where is DATABASE_URL used?" |
Configuration and environment-variable usage |
| "Which modules depend on this package?" |
Package/module dependency traversal |
| "Why is this service reachable?" |
Containment, registration, route, and dependency edges |
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
| Error |
Recovery |
ontoly command not found |
Use npx ontoly --help or install Ontoly as a dev dependency |
| Build fails |
Report command, exit code, diagnostics, and smallest blocker |
| No graph output |
Confirm repository root, package manager, permissions, and Ontoly config |
| Ambiguous node |
List candidate node IDs/kinds/locations before answering |
| Low graph coverage |
Answer only evidenced parts and label missing coverage |
Anti-Patterns
| Prohibited |
Correct |
| Search files first for architecture questions |
Build/query Ontoly graph first |
| Claim certainty without graph evidence |
Include nodes, edges, diagnostics, and confidence |
| Hide graph gaps with manual inference |
State missing node/edge/framework coverage |
| Compare raw node names across tools |
Compare semantic concepts and relationship evidence |
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
1---2name: ontoly3description: Deterministic Software Graph analysis via Ontoly CLI and MCP. Use when: (1) Codebase architecture, dependency, route, service, module, configuration, or impact questions need graph evidence, (2) A repository should be analyzed before source search, (3) You need a persistent SoftwareGraph.json for validation, MCP, or agent workflows. Triggers: "build software graph", "trace route", "impact analysis", "architecture summary", "dependency graph", "what uses this", "Ontoly".4---56# Ontoly - Software Graph Analysis78Build 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.910## Prerequisites1112```bash13# Recommended: run through npx so the current published CLI is used14npx ontoly --help15```1617If the project already has Ontoly installed, prefer the repository-local package manager command, such as `pnpm ontoly`, `npm exec ontoly`, or `npx ontoly`.1819## Quick Start2021```bash22# From the repository root23npx ontoly build .2425# Start MCP for agent integrations26npx ontoly mcp2728# Inspect available commands29npx ontoly --help30```3132Expected outputs may include `.ontoly/SoftwareGraph.json`, diagnostics, graph statistics, indexes, and metadata depending on the Ontoly version and repository configuration.3334## Tool Routing Policy3536### Prefer Ontoly Before File Search3738| Task | Avoid | Use Ontoly |39|------|-------|------------|40| Architecture summary | Reading every README/source folder | Build graph, inspect graph statistics and architecture report |41| Impact analysis | Grep for identifier text | Query dependencies, callers, callees, and related nodes |42| Request flow | Manually follow controller/service files | Trace route/controller/service relationships |43| Configuration audit | Search `.env` names only | Query configuration and environment-variable nodes |44| Dead code review | Guess from unused exports | Use graph diagnostics and unreachable/dead-code evidence |4546### When to Use Built-in Tools4748- Ontoly is not installed and cannot be run in the environment49- The graph reports low coverage or missing framework support50- The question depends on source comments, prose documentation, generated artifacts, or runtime data not represented in the graph51- You need to verify a suspected graph gap5253## Workflow5455### Phase 1: Graph Readiness56571. Locate the repository root.582. Check for an existing Ontoly graph, usually `.ontoly/SoftwareGraph.json`.593. If missing or stale, run:6061```bash62npx ontoly build .63```64654. Review diagnostics, graph hash, node count, edge count, framework detection, and coverage/trust signals before answering.6667### Phase 2: Query6869Choose the narrowest query or capability for the question:7071| Question Type | Query Direction |72|---------------|-----------------|73| "What owns auth?" | Services, controllers, modules, packages |74| "What handles POST /login?" | Routes, handlers, request lifecycle |75| "What breaks if I remove X?" | Impact analysis, consumers, dependency traversal |76| "Where is DATABASE_URL used?" | Configuration and environment-variable usage |77| "Which modules depend on this package?" | Package/module dependency traversal |78| "Why is this service reachable?" | Containment, registration, route, and dependency edges |7980### Phase 3: Answer with Evidence8182Always include:8384- direct answer85- relevant node IDs and node kinds86- relationship names and directions87- source locations when present88- diagnostics or graph-quality warnings89- confidence derived from graph evidence9091## Output Format9293```markdown94## Answer95{Concise answer.}9697## Graph Evidence98| Type | Evidence |99|------|----------|100| Node | `{nodeId}` ({kind}) |101| Edge | `{source} --RELATIONSHIP--> {target}` |102| Location | `{file}:{line}` |103| Diagnostic | `{code}: {message}` |104105## Confidence106{High/Medium/Low} because {specific graph evidence, coverage, diagnostics}.107108## Fallbacks109{Any source search used, or graph gaps that prevented a full answer.}110```111112## Common Commands113114```bash115# Build a graph for the current repository116npx ontoly build .117118# Build a graph for a specific repository119npx ontoly build /path/to/repo120121# Start the MCP server122npx ontoly mcp123124# Validate skills if using Ontoly Agent Skills125npx ontoly skills validate126```127128## Error Handling129130| Error | Recovery |131|-------|----------|132| `ontoly` command not found | Use `npx ontoly --help` or install Ontoly as a dev dependency |133| Build fails | Report command, exit code, diagnostics, and smallest blocker |134| No graph output | Confirm repository root, package manager, permissions, and Ontoly config |135| Ambiguous node | List candidate node IDs/kinds/locations before answering |136| Low graph coverage | Answer only evidenced parts and label missing coverage |137138## Anti-Patterns139140| Prohibited | Correct |141|------------|---------|142| Search files first for architecture questions | Build/query Ontoly graph first |143| Claim certainty without graph evidence | Include nodes, edges, diagnostics, and confidence |144| Hide graph gaps with manual inference | State missing node/edge/framework coverage |145| Compare raw node names across tools | Compare semantic concepts and relationship evidence |146147## Limitations148149- Requires the Ontoly CLI package or repository-local installation150- Graph completeness depends on the language and framework analyzers available in the installed Ontoly version151- Runtime-only behavior may require additional source or runtime evidence
Dianel555