reponova

⚠️ Alpha — Active Development This package is under active development. APIs, config format, and CLI may change between releases. It's already usable, but expect rough edges. If you find a bug or something doesn't work as expected, please open an issue — it helps a lot.

Knowledge graph builder & MCP server for AI code assistants. Builds a searchable, queryable graph of your codebase — then exposes it to AI agents via MCP tools.

What It Does

1. Extracts symbols (functions, classes, modules, docs, diagrams) from your codebase using tree-sitter WASM parsers
2. Builds a knowledge graph with cross-file and cross-repo relationships
3. Detects communities (Louvain) and generates embeddings (TF-IDF or ONNX)
4. Serves the graph over MCP — AI agents can search, trace impact, find paths, and explore architecture

Your Codebase                        reponova
┌──────────────────┐                ┌───────────────────────────────────┐
│ Python / TS / JS │                │ MCP Server (stdio)                │
│ Markdown / Docs  │  reponova      │ ├─ graph_search (+BFS/DFS expand) │
│ Diagrams / SVG   │  build         │ ├─ graph_impact (blast radius)    │
│                  │ ────────────►  │ ├─ graph_path (weighted Dijkstra) │
│ Multi-repo       │                │ ├─ graph_explain (node detail)    │
└──────────────────┘                │ ├─ graph_similar (semantic)       │
                                    │ ├─ graph_context (smart context)  │
                                    │ ├─ graph_ask (NL query)           │
                                    │ ├─ graph_community (membership)   │
                                    │ ├─ graph_hotspots (god nodes)     │
                                    │ ├─ graph_outline (tree-sitter)    │
                                    │ ├─ graph_docs (doc search)        │
                                    │ └─ graph_status                   │
                                    └───────────────────────────────────┘

Zero external runtime dependencies — no Python, no Docker, no database servers. Everything runs locally in Node.js.

Install

npm install -g reponova
# or run directly
npx reponova

Requires Node.js >= 18.

Quick Start

1. Install into your editor (registers MCP server, hook, skill, and config):

   reponova install --target opencode   # or: cursor, claude, vscode

2. Build the knowledge graph:

   reponova build

3. The MCP server starts automatically with your editor. Use the graph tools directly from the AI assistant.

MCP Tools

CLI Reference

install — Set up editor integration

reponova install --target <editor>

What it does:

1. Registers the MCP server in the editor's config
2. Installs a hook/rule that reminds the AI agent to use graph tools
3. Installs a skill file that teaches the AI agent how to use each tool
4. Writes reponova.yml config inside the editor directory

build — Build the knowledge graph

reponova build [--config <path>] [--force]

The build pipeline:

1. Detects source files, documentation, and diagrams
2. Extracts symbols and relationships using tree-sitter WASM parsers
3. Builds the knowledge graph with cross-file and cross-repo edges
4. Detects communities (Louvain algorithm)
5. Generates embeddings (TF-IDF by default, or ONNX MiniLM)
6. Generates community summaries and node descriptions (algorithmic or LLM-enhanced)
7. Generates graph.html and graph_communities.html interactive visualizations
8. Generates the search index (graph_search.db)
9. Generates code outlines and report.md

mcp — Start the MCP server

reponova mcp [--graph <path>]

Starts the MCP server over stdio. Normally launched automatically by the editor.

models — Manage local models

reponova models list              # Show downloaded models
reponova models download          # Download embedding/LLM models
reponova models remove <name>     # Remove a downloaded model

check — Verify installation

reponova check [--graph <path>]

Verifies the graph exists and reports basic stats.

Configuration

The install command writes reponova.yml into the editor directory. All paths are relative to the config file's location.

The config is auto-detected from these locations (in order):

1. Explicit --config argument
2. reponova.yml in the project root
3. .opencode/reponova.yml, .cursor/reponova.yml, .claude/reponova.yml, .vscode/reponova.yml

Full config reference

# Where to write build output
output: ../reponova-out

# Repositories to include in the build
repos:
  - name: api-service
    path: ../services/api
  - name: core-lib
    path: ../services/core

# Build options
build:
  mode: monorepo                  # "monorepo" or "separate"
  exclude: []                     # directory names to skip (e.g. dist_package, .tox)
  incremental: true               # use file hash cache for incremental rebuilds
  html: true                      # generate interactive HTML visualizations
  # html_min_degree: 3            # if set, only include nodes with degree >= this value in HTML

  # Documentation extraction
  docs:
    enabled: true
    patterns:                     # glob patterns to match
      - "**/*.md"
      - "**/*.txt"
      - "**/*.rst"
    exclude:
      - "**/CHANGELOG.md"
      - "**/node_modules/**"
    max_file_size_kb: 500

  # Diagram/image extraction
  images:
    enabled: true
    patterns:
      - "**/*.puml"
      - "**/*.plantuml"
      - "**/*.svg"
    exclude:
      - "**/node_modules/**"
    parse_puml: true
    parse_svg_text: true

  # Embeddings: vector representations for semantic search
  embeddings:
    enabled: true
    method: tfidf                 # "tfidf" (fast, default) or "onnx" (MiniLM, more accurate)

  # Summaries: community summaries and node descriptions
  summaries:
    enabled: true
    max_communities: 0            # 0 = no limit
    generate_node_descriptions: true
    node_description_threshold: 0.8  # top 20% nodes by degree

  # LLM: local language model for enhanced summaries (optional, opt-in)
  llm:
    enabled: false                # set true to use Qwen 0.5B for richer summaries
    model: qwen2.5-0.5b-instruct
    gpu: auto                     # "auto", "cpu", or "cuda"/"vulkan"/"metal"

# Outline generation (language auto-detected from file extension)
outlines:
  enabled: true
  paths:
    - "src/**/*.py"
    - "src/**/*.ts"
    - "src/**/*.js"
  exclude:
    - "**/__pycache__/**"
    - "**/node_modules/**"
    - "**/dist/**"

Programmatic API

import {
  openDatabase,
  initializeSchema,
  populateDatabase,
  loadGraphData,
  searchNodes,
  analyzeImpact,
  findShortestPath,
  getNodeDetail,
} from "reponova";

const graphData = loadGraphData("./reponova-out/graph.json");
const db = await openDatabase(":memory:");
initializeSchema(db);
populateDatabase(db, graphData);

const results = searchNodes(db, "authentication", { top_k: 5, type: "function" });
const impact = analyzeImpact(db, "Function:authenticate_user", { max_depth: 3 });

License

MIT