Reponova

🤖 RepoNova 🔭

Turn your codebase into a knowledge graph. Query it with AI.

Knowledge graph builder & MCP server for AI code assistants. Extracts symbols, relationships, and semantics from your code — then exposes the entire structure as 11 graph tools that any MCP-compatible agent can use.

---

> ⚠️ Alpha — Active Development > APIs, config format, and CLI may change between releases. > Already usable in production workflows. Open an issue if something doesn't work.

---

Why RepoNova?

AI agents read files one at a time. They don't understand how your codebase fits together — which functions call what, which modules depend on which, where the architectural bottlenecks are.

RepoNova fixes that. It builds a persistent knowledge graph of your entire codebase (or multiple repos) and gives your AI agent 11 specialized tools to query it: search, impact analysis, shortest path, semantic similarity, community detection, and more.

> One build. Persistent graph. Instant queries across sessions. > No re-reading files. No burning tokens on context. The graph remembers everything.

What makes it different

• Zero external dependencies — no Python, no Docker, no database servers. Pure Node.js
• Plugin-based language support — install only what your workspace needs via reponova lang suggest (Markdown is the only built-in)
• Multi-repo support — build one graph spanning multiple repositories
• Smart incremental builds — SHA256 file hashing, per-phase config change detection
• Intelligent enrichment — your AI agent or a configured LLM provider generates architectural descriptions, community profiles, and routing decisions
• 11 MCP tools — from text search to weighted Dijkstra, semantic similarity to structural queries
• Works with any AI coding agent — OpenCode, Cursor, Claude Code, VS Code Copilot

---

How it works

  Your Codebase                      /reponova-enrich                             AI Agent
  ─────────────                      ────────────────                             ────────

  Source Code          ──────────►   1. tree-sitter AST parsing                   graph_search
  Markdown / Docs                    2. Symbol + edge extraction        ──────►   graph_impact
  Diagrams (plugins)                 3. Louvain communities                       graph_path
  Multi-repo                         4. Enrichment (summaries + descriptions)     graph_similar
                                     5. TF-IDF / ONNX / API embeddings
                                     6. HTML visualizations                       ... (11 tools)

Language extraction lives in [language plugins](#available-plugins) — only Markdown is built-in. Run reponova lang suggest to scan your repos and install the ones you need (the [official @reponova/lang-* catalogue](#available-plugins) plus any community plugin). See [Contributing](#contributing) to author a new plugin.

---

Quick Start

1. Install into your editor

reponova install --target opencode

Supported targets: opencode, cursor, claude, vscode

Artifacts installed per editor:

| Editor | MCP Config | Hook / Plugin | MCP Skill | Enrich Command | Config | |--------|-----------|---------------|-----------|----------------|--------| | OpenCode | .opencode/opencode.json | .opencode/plugins/reponova.js | .opencode/skills/reponova-mcp/SKILL.md | .opencode/commands/reponova-enrich.md | .opencode/reponova.yml | | Cursor | .cursor/mcp.json | .cursor/rules/reponova-mcp.mdc | (embedded in rule) | .cursor/commands/reponova-enrich.md | .cursor/reponova.yml | | Claude Code | claude mcp add (manual) | .claude/settings.json (PreToolUse) | .claude/skills/reponova-mcp/SKILL.md | .claude/skills/reponova-enrich/SKILL.md | .claude/reponova.yml | | VS Code | .vscode/mcp.json | (skill auto-loads) | .github/skills/reponova-mcp/SKILL.md | .github/skills/reponova-enrich/SKILL.md | .vscode/reponova.yml |

2. Install language plugins for your workspace

reponova lang suggest

Scans every repo in the workspace and queries the public npm registry for matching language plugins. Pick what you need; reponova lang add then declares them in reponova.yml. See [Available Plugins](#available-plugins) for the official catalogue.

3. Build and enrich the graph

Type /reponova-enrich in your editor. This single command handles the entire pipeline:

• Builds the structural graph (file detection, AST parsing, community detection)
• Generates architectural node descriptions
• Profiles communities with meaningful labels
• Routes misplaced nodes to correct communities
• Proposes and applies structural merges/splits
• Runs downstream phases (search index, embeddings, HTML visualizations)

Your AI agent acts as the reasoning engine — no API keys, no local models, no downloads.

> Headless alternative: Run reponova build from the CLI for a fully algorithmic build (no LLM). For automated LLM enrichment, configure enrich.provider in reponova.yml — then reponova build handles everything including intelligent enrichment.

4. Use it

The MCP server starts automatically. Your AI agent now has 11 graph tools.

You: "What would be the impact of refactoring the authenticate function?"
Agent: [calls graph_impact] → shows upstream/downstream blast radius across repos

Keeping the graph fresh

After code changes, re-run /reponova-enrich — only changed files are re-parsed, only affected steps re-run.

For CI or headless environments: reponova build (incremental by default, --force for full rebuild).

---

MCP Tools

11 specialized tools exposed over MCP (stdio):

| Tool | Description | |------|-------------| | graph_search | 🔍 Full-text search across nodes. Filter by type, repo. Expand results with BFS/DFS. | | graph_impact | 💥 Blast radius analysis — find all upstream/downstream dependents of any symbol. | | graph_path | 🛤️ Weighted shortest path (Dijkstra) between two symbols. Filter by edge type. | | graph_explain | 📋 Full detail on a node: edges, community, centrality metrics, signature, docstring. | | graph_similar | 🧲 Semantic similarity search using vector embeddings (TF-IDF, ONNX, or remote provider). | | graph_context | 🧠 Smart context builder with token budget — combines search + vectors + graph expansion. | | graph_community | 🏘️ List all nodes in a community, ranked by degree centrality. | | graph_hotspots | 🔥 God nodes / architectural bottlenecks — most connected symbols in the graph. | | graph_outline | 🗂️ Tree-sitter code outline: functions, classes, imports with signatures and line ranges. | | graph_docs | 📄 Search documentation nodes (markdown, text, rst). | | graph_status | 📊 Graph metadata: node/edge counts, repos, build timestamp, version. |

---

Enrichment

RepoNova supports two enrichment modes:

| Mode | How it works | Requires | |------|-------------|----------| | Agent-driven | /reponova-enrich — your AI agent builds the graph AND acts as the reasoning engine for enrichment. Complete pipeline in one command. | Any AI coding agent | | Automated | reponova build with enrich.provider configured — an external LLM generates descriptions, profiles, and routing decisions during the build. | A configured LLM provider in reponova.yml |

What enrichment does

The enrichment pipeline (7 steps) transforms a raw structural graph into an architecturally-aware knowledge base:

| Step | What | |------|------| | 0 | Classify boundary nodes (candidates for rerouting) + compute edge density | | 1 | Generate architectural descriptions for high-degree nodes | | 2 | Profile each community (label, purpose, misfits) | | 3 | Route misfit nodes to better communities based on profiles | | 4 | Detect merge/split opportunities across communities | | 5 | Apply routing + restructure mutations to the graph | | 6 | Re-profile affected communities | | 7 | Finalize output files (graph-enriched.json, node_descriptions.json, community_summaries.json) |

Agent-driven enrichment (/reponova-enrich)

The installed command guides the agent through the full pipeline:

You: /reponova-enrich
Agent: [builds structural graph]
       [reads input batches, reasons about architecture, writes output batches]
       [CLI merges results, applies mutations]
       [runs downstream phases: search index, embeddings, HTML]

The agent uses reponova enrich:* subcommands for batch preparation and merging. All reasoning (descriptions, profiles, routing decisions) comes from the agent itself.

---

CLI Reference

reponova install

Set up editor integration (MCP server, plugin/hook, skills, enrich command, config).

reponova install --target  [--graph ]

| Option | Required | Description | |--------|----------|-------------| | --target | Yes | opencode, cursor, claude, vscode | | --graph | No | Path to output directory. Default: ./reponova-out |

reponova build

Run the full build pipeline (incremental by default).

reponova build [--config ] [--force] [--target ] [--start-after ] [--check ]

| Option | Required | Description | |--------|----------|-------------| | --config | No | Path to reponova.yml (default: auto-detected) | | --force | No | Ignore all caches and rerun every phase | | --target | No | Run only these phases and their dependencies (comma-separated, e.g. communities,outlines) | | --start-after | No | Run only phases downstream of this phase | | --check | No | Check if a phase needs to run (exit 0 = up to date, exit 1 = needs run) |

Build pipeline (9 DAG phases, 5 levels):

Level 0: file-detection
Level 1: graph, outlines                         (parallel)
Level 2: communities
Level 3: enrich
Level 4: search-index, embeddings, html, report  (parallel)

| Phase | What it does | |-------|-------------| | file-detection | Discover files by registered type (built-in docs + plugin extensions) | | graph | Parse with tree-sitter, extract symbols/calls/imports/inheritance, build graph | | outlines | Generate tree-sitter code outlines per file (SHA256 hashing — skip unchanged) | | communities | Louvain community detection, write graph.json | | enrich | Generate graph-enriched.json, community summaries, node descriptions (algorithmic or LLM) | | search-index | SQLite search index (graph_search.db) | | embeddings | Incremental embeddings (TF-IDF, ONNX, or remote provider) | | html | Interactive visualizations (graph.html, graph_communities.html) | | report | Build report with stats, hotspots, community breakdown |

reponova enrich

Run the intelligent enrichment pipeline with a configured LLM provider. Builds up to communities if needed, runs all enrichment steps, seals the cache.

reponova enrich [--config ]

| Option | Required | Description | |--------|----------|-------------| | --config | No | Path to reponova.yml (default: auto-detected) |

> Note: Does NOT run downstream phases (search-index, embeddings, html, report). Run reponova build --start-after enrich afterwards to complete the pipeline.

reponova enrich:*

Step-by-step enrichment subcommands for IDE/agent workflows.

reponova enrich:metrics                        # Step 0: candidates + edge density
reponova enrich:prepare                  # Prepare input batches
reponova enrich:merge                    # Merge output batches
reponova enrich:apply                          # Step 5: apply routing + restructure
reponova enrich:finalize                       # Step 7: produce final output files

| Step | What it produces | |------|-----------------| | descriptions | Architectural descriptions for high-degree nodes | | profiles | Community profiles (label, purpose, misfits) | | routing | Routing decisions for boundary candidates | | restructure | Merge/split proposals across communities | | updated-profiles | Re-profiled communities after mutations |

| Option | Required | Description | |--------|----------|-------------| | --config | No | Path to reponova.yml (default: auto-detected) |

reponova mcp

Start the MCP server (stdio transport). Normally launched automatically by the editor.

reponova mcp [--graph ]

| Option | Required | Description | |--------|----------|-------------| | --graph | No | Path to output directory. Default: ./reponova-out |

reponova check

Health check for graph artifacts, search index, outlines, tree-sitter runtime, and declared language plugins. Exits 1 if anything is missing — declared-but-not-installed plugins are listed with the exact lang add command to fix them.

reponova check [--config ] [--graph ]

| Option | Required | Description | |--------|----------|-------------| | --config | No | Path to reponova.yml (default: auto-detected) | | --graph | No | Path to output directory. Default: ./reponova-out |

reponova lang

Manage language plugins. The package manager (npm / pnpm / yarn / bun) and install scope (global / local / linked) are detected automatically.

reponova lang  [args] [flags]

| Subcommand | Description | |------------|-------------| | add | Install a language plugin and declare it in reponova.yml | | remove | Remove a plugin from reponova.yml and uninstall its package | | list | List declared plugins with their load status | | suggest | Scan repos, find used file extensions, propose matching plugins (interactive) |

| Flag | Applies to | Description | |------|-----------|-------------| | --config-only | remove | Only update reponova.yml, keep the package installed | | --purge-global | remove | In global context, uninstall without confirmation prompt | | --dry-run | suggest | Print the report only, skip the interactive prompt | | --yes | suggest | Install all suggestions without prompting (CI mode) |

By default, remove on a globally-installed reponova prompts before touching the system-wide package (and skips it with a warning in non-interactive shells). suggest queries the public npm registry for every package tagged with the reponova-language keyword; @reponova/lang-* packages are ranked first as "official".

reponova cache

Inspect and manage per-phase cache state. Exactly one operation is required. Phases are the same as in [reponova build](#reponova-build).

reponova cache --status                        # Show cache status for all phases
reponova cache --check                  # Check if fresh (exit 0 = fresh, exit 1 = stale)
reponova cache --seal                   # Manually seal (marks as up-to-date)
reponova cache --invalidate             # Invalidate (forces re-run on next build)

| Option | Required | Description | |--------|----------|-------------| | --config | No | Path to reponova.yml (default: auto-detected) |

reponova models

Manage local AI models (ONNX embeddings, GGUF LLM weights).

reponova models 

| Subcommand | Description | |------------|-------------| | status | Show configured and cached models | | download | Pre-download all models needed by config | | remove | Remove a specific cached model | | clear | Remove all cached models |

---

Supported Languages

RepoNova uses a plugin system for language support. Only Markdown is built-in; everything else is provided by external plugin packages (see [Contributing](#contributing) for how to create one).

Built-in

| Language | Extensions | Parser | Symbols Extracted | |----------|-----------|--------|-------------------| | Markdown | .md, .txt, .rst | Regex | Documents, sections (as containment hierarchy) |

Available Plugins

All official plugins are developed in the [`repono

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CristianoCiuti
• Source: CristianoCiuti/reponova
• License: MIT

Install and usage instructions live in the source repository linked above.