A code knowledge graph built for LLM agents — accurate answers, minimal tokens, maximum speed.
Try it now: User Guide (install → index → query) · Download latest release · Agent skill · AGENTS.md for LLM workflows
AI coding agents default to reading files sequentially. That burns context, misses structure, and produces confident wrong answers about impact and dependencies. rgBuilder indexes the whole repository once into a rich graph with pre-computed reachability, then serves compact, deterministic query results — so agents (and humans) get the right slice of the codebase without loading it into the prompt.
Quick cli tour:
user-guide-cli.mp4
Dashboard tour (optional visualization):
rgbuilder-feature-demo.mp4
Goal: make LLM-assisted development more accurate while using fewer tokens.
| Without rgBuilder | With rgBuilder |
|---|---|
| Agent reads dozens of files to guess dependencies | Agent calls blast-radius Symbol → structured impact JSON |
| “What calls this?” requires search + inference | gql returns exact graph matches |
| Migration planning from partial context | Migration planner — package roadmap, dual ordering, tunable scores, interactive graph |
| Repeated file dumps every turn | One discover, then cache-backed queries via CLI or -f json |
rgBuilder answers reachability and relation questions deterministically from the indexed graph. The LLM reasons on summaries and facts, not raw repo grep — fewer tokens, less hallucination, faster turns.
Primary outputs for agents: -f json on discover, gql, blast-radius, metrics, semantic, communities, cpg, check, slice, and inspect. File export uses export --export-format (not stdout JSON). See JSON API.
Most codebase tools stop at text search, file trees, or a shallow call graph. rgBuilder goes further — compiler-grade structure and security analysis, pre-computed at index time, queryable in milliseconds. That is what makes agent answers trustworthy.
| Feature | What it gives you | Design doc |
|---|---|---|
| Semantic search | Natural-language and keyword search over functions — code-daemon (default), offline vocab / hash, Hamming retrieval, late fusion with blast/PageRank/sketches | semantic-search-design.md |
| Blast radius | Pre-computed reachability over the call graph — upstream impact, scores, policy gates, sub-second on large repos | blast-radius-design.md |
| Program slicing | Backward / forward slice — only the statements that affect (or are affected by) a line and variable | program-slicing-design.md |
| Taint analysis | Source → sink flows (HTTP params → SQL, shell, render, …) with sanitizer awareness | taint-analysis-design.md |
| CFG | Control-flow graph per function — branches, loops, executable paths | cfg-design.md |
| PDG | Program dependence graph — data and control deps between statements; foundation for slice and taint | pdg-design.md |
| Dominance | Dominator trees and frontiers — the same structures compilers use for advanced analysis | dominance-design.md |
| Hybrid CPG | Unified façade over L_repo CALL graph + L_proc CFG/PDG — mutations, flows, calls (cpg) |
hybrid-cpg-plan.md |
| GQL | Graph query language over 30+ relation types — inventory, call chains, patterns | gql-design.md |
| Graph metrics | PageRank, betweenness, communities (label propagation) on the live call graph | graph-metrics-design.md |
| Named communities | communities CLI — list / refresh heuristic labels over label-propagation clusters |
graph-metrics-design.md |
| Migration planner | Package-level roadmap — PageRank + harmonic centrality − blast radius; dependency-aware schedule and priority rank | migration-planner-design.md |
| CI policy checks | check — fail builds when blast-radius rules are violated on touched symbols |
ci-policy-checks-design.md |
All of the above share one index: run discover once (use discover --with-cfg / --with-taint for CFG/PDG/taint archives; add --export-migration-hints when you need a migration plan JSON). Semantic search is opt-in: rg-build semantic index after discover. Explore in the CLI and pipe JSON to agents. An optional browser UI exists after discover --with-dashboard — see dashboard user guide if you want it.
Deep dive → Introduction · User Guide · Feature designs (contributors)
rgBuilder is async and parallel by design — discovery walks the tree, parses languages concurrently, and builds analytics on the graph in parallel (Rayon + Tokio throughout the pipeline).
- Full discovery in seconds on typical repos (not minutes of ad-hoc agent exploration)
- Reachability compressed — enterprise-scale call graphs stored in compact on-disk snapshots, not gigabytes in RAM
- HTTP
serve— dashboard +/api/queryon port 8080; optionalserve --daemonsocket for blast-radius warm path
Index once → query many times. That is the agent workflow.
Agent / script / human
│
▼
rg-build gql | blast-radius | metrics | semantic | export -f json
│
▼
.rgbuilder/ ← graph snapshot + reachability engine + indexes
▲
│
discover . ← async parallel index (seconds)
▲
│
Your repository
Use the features above together for migration and modernization work:
- Migration planner — package-level graph, tunable scoring presets, dependency-aware schedule vs. priority rank
- Blast radius + metrics — see fan-in and architectural hotspots before moving a service or framework
- GQL + export — inventory symbols and ship subgraphs to downstream tools
- Slice + taint — validate data-flow assumptions agents often get wrong
check— enforce blast-radius policy in CI while agents (or humans) land changes
After deep discover + --export-migration-hints, read .rgbuilder/migration_plan.json (agents) or optionally open a dashboard Migration tab if you also passed --with-dashboard:
Scoring and package ordering; community coloring uses label propagation — see graph metrics naming.
- Package macro graph — aggregates functions into path-derived package labels (Java package paths, Rust/C
/src/modules) - Dual ordering — scheduled step (Kahn topological sort, callee before caller) and priority rank (score-only)
- Scoring —
Priority = α·PageRank + β·Harmonic − γ·Blast; presets include Hybrid Default, Foundational First, Dense Cluster Extraction, Risk Mitigation - CLI export —
--export-migration-hintswrites a preset-tuned plan (default.rgbuilder/migration_plan.json);--with-dashboardadditionally copies UI assets under.rgbuilder/dashboard/
rg-build discover . --with-cfg --with-security --with-taint --with-harmonic --export-migration-hints
# optional UI: add --with-dashboard, then: rg-build serve --open
rg-build serve # http://127.0.0.1:8080/ → Migration tabDesign → Migration planner design · Workflow → Building a migration plan
All feature designs → docs/design/
rgBuilder does not run the Leiden algorithm today. What ships is label propagation (Raghavan et al., 2007) with Newman modularity scoring, plus hub stripping and deterministic tie-breaking. Docs/UI still say “Louvain” in places (louvain_community_id, migration layout), and TASK_PLAN.md lists Leiden as planned but unimplemented.
| Name in repo | What it actually is |
|---|---|
CommunityDetector |
Label propagation on Calls + Uses |
| “Louvain” in dashboard/migration | Majority vote of label-propagation ids |
| Leiden (task 2.1.1) | Not implemented |
Full detail → Graph metrics — community naming.
Walkthrough on the in-tree Spring Boot fixture → ecommerce-java example (User Guide).
Research map — which papers rgBuilder implements, which inspire the roadmap, and where to propose changes → Further reading.
Install from GitHub Releases or build from source:
git clone https://github.com/sshaaf/rgBuilder.git
cd rgBuilder
git lfs pull # bundled code-daemon ONNX weights (~206 MB)
cargo build --releaseDiscover (build the graph + reachability caches):
git clone https://github.com/konveyor-ecosystem/coolstore.git
cd coolstore
rg-build discover .
# agent-friendly telemetry:
rg-build -f json discover . | jq '.metrics'Query (compact answers instead of file dumps):
# Graph inventory for the agent
rg-build -f json gql 'MATCH (n:Function) RETURN n LIMIT 10'
# Impact — critical before the agent edits a symbol
rg-build -f json blast-radius ShoppingCartService
# Hotspots — where migration/refactor pain concentrates
rg-build -f json metrics --pagerank --communities
# Package migration roadmap (graph + plan JSON for agents)
rg-build discover . --with-cfg --with-security --with-taint --with-dashboard --with-harmonic --export-migration-hintsConcepts → Introduction · Commands → User Guide
Example deep-analysis commands (after discover --with-cfg):
rg-build inspect checkout cfg # CFG / PDG / dominance (function symbol)
rg-build slice src/Foo.java --line 42 --variable x
rg-build slice src/Foo.java --line 10 --variable req --taint
rg-build semantic index --embedder vocab # offline; or default code-daemon after git lfs pull
rg-build -f json semantic query "checkout flow" --limit 10| R | Meaning |
|---|---|
| Rust | Memory-safe, predictable performance at scale — the foundation for parsing large monorepos without blowing the heap |
| Reachability | Pre-computed call reachability (sparse bitsets, not multi‑GB dense matrices) so “what breaks if I change this?” stays sub-second |
| Rich code graph | 30+ typed relations — CALLS, IMPORTS, CONTAINS, IMPLEMENTS, and more — not just files and folders |
Together: rgBuilder is the reachability builder — it constructs the graph and the compressed reachability engine agents need for trustworthy structural reasoning.
Algorithm and complexity details: crate READMEs under crates/rgbuilder-analysis/ and CLI I/O sanity QE for automated perf gates.
Quick links into Introduction — see Where most tools stop for the differentiators.
| Command | Introduction |
|---|---|
discover |
Indexing |
gql |
Graph queries |
blast-radius |
Blast radius |
slice |
Program slicing · Taint |
inspect |
CFG, PDG, dominance |
metrics |
Graph metrics |
semantic |
Semantic search (opt-in index + query) |
communities |
Graph metrics · User Guide |
cpg |
Hybrid CPG |
export |
Export |
check |
CI policy |
serve |
HTTP server |
Dashboard — visual exploration after discover --with-dashboard (.rgbuilder/dashboard/). See Feature designs for per-tab engineering docs.
Migration export — discover --export-migration-hints (alias --export-migration-plan; optional --migration-preset, --migration-order scheduled|priority).
Languages — nine Tier 1 languages (Rust, Python, Java, Go, TypeScript, JavaScript, C#, C, C++) plus config/IaC plugins. See Languages.
| Document | For |
|---|---|
| Documentation index | Map of all docs by persona |
| Introduction | Concepts — graph, reachability, capability map |
| User Guide | Install, ecommerce-java fixture, every CLI command |
| Agent skill | Canonical agent playbook — NL routing + CLI samples |
| AGENTS.md | Minimal agent contract (points at skill) |
| Agent recipes | Copy-paste automation workflows |
| JSON API | Parse -f json payloads + field catalogs |
| HTTP API | rg-build serve → /api/query and /api/semantic/* |
| Policy format | check / blast policy JSON |
| Languages | Supported languages and tiers |
| Further reading | Research implemented vs inspired |
| CLI I/O sanity QE | Subprocess JSON contract and release perf gates (contributors) |
| Feature designs | Engineering design docs (contributors) |
| Migration planner design | Package graph, scoring, ordering (contributors) |
| Building a migration plan | End-to-end migration workflow |
| Dashboard user guide | Optional browser UI |
| CONTRIBUTING.md | Dev setup and PR expectations |
| Releasing | Tags and GitHub Releases (contributors) |
cargo test
cargo build --release
# See CONTRIBUTING.md for dashboard build and golden-repo checksMIT — see LICENSE.