rgBuilder for AI agents

rgBuilder is designed so agents answer structural questions from a pre-built graph instead of reading whole files into context.

Full JSON reference: docs/json-api.md (also on the site: sshaaf.github.io/rgBuilder/docs/json-api/)
Copy-paste recipes: docs/agent-recipes.md
Human walkthrough: docs/user-guide.md
Docs hub: docs/README.md · site docs

Do not open the browser dashboard unless the user asks for a visual UI — default to CLI -f json.

Agent workflow

1. rg-build discover .              # once per repo (or after large changes)
2. rg-build -f json <command>      # compact facts on stdout
3. Parse schema_version + payload   # never scrape stderr for JSON

Set REPO to the repository root (where .rgbuilder/ lives):

export REPO=/path/to/repo
rg-build -r "$REPO" -f json gql 'MATCH (n:Function) RETURN n LIMIT 20'

High-value commands (low token cost)

Intent	Command
Inventory functions	`rg-build -f json gql --macro-name all_functions unused`
List communities	`rg-build -f json gql --macro-name all_communities unused`
Find symbol by pattern	`rg-build -f json gql "MATCH (n:Function) WHERE n.name LIKE 'Service' RETURN n LIMIT 20"`
Find by FQN (not `n.name`)	`rg-build -f json gql "MATCH (n:Class) WHERE n.qualified_name = 'com.example.Foo' RETURN n"`
Community members	`rg-build -f json gql "MATCH (f:Function) WHERE f.community_id = '12' RETURN f LIMIT 20"`
Natural-language function search	`rg-build semantic index` (or `--embedder vocab`) then `rg-build -f json semantic query "checkout flow" --limit 10`
Community semantic search	`rg-build -f json semantic query "checkout" --scope community --limit 10`
Impact before editing	`rg-build -f json blast-radius <Symbol> [--depth N]`
Architectural hotspots	`rg-build -f json metrics --pagerank`
Call neighborhood	`rg-build -f json gql "MATCH (a:Function)-[:CALLS*1..3]->(b:Function) RETURN a,b LIMIT 50"`
Hybrid CPG status / CALL / PDG / slice	`rg-build -f json cpg status` then `cpg function\|calls\|pdg\|slice` (needs `discover --with-cfg` for PDG/slice)
Field mutations (cart / DTO safety)	`rg-build -f json cpg mutations --type ShoppingCart --exclude-ctors` (ecommerce CoolStore; or any type name; needs `--with-cfg`)
Data flows / slice (CPG)	`rg-build -f json cpg flows FILE --line N --variable V --function F [--direction forward\|backward] [--with-alias]`
Loop-carried DFG tags	`rg-build discover . --with-cfg --with-dfg-loops` (tags `DataDependency.loop_carried` in PDG)
AST skeleton	`rg-build discover --with-ast-skeleton` then `rg-build -f json cpg ast <Symbol>`
CPG export	`rg-build cpg export --format graphson --output cpg.json [--path-contains src/]`
Migration plan	`rg-build discover . --with-cfg --with-security --with-taint --with-dashboard --with-harmonic --export-migration-hints` then read `.rgbuilder/migration_plan.json` (or dashboard copy)
CI gate on changes	`rg-build -f json check --policy-file policy.json` (exit 1 = violations)

Repeated queries in one session

Option A — HTTP (recommended):

rg-build -r "$REPO" serve --open
# POST http://127.0.0.1:8080/api/query  {"query":"MATCH (n:Function) RETURN n LIMIT 5"}

See docs/http-api.md.

Option B — Legacy socket daemon:

rg-build -r "$REPO" serve --daemon
# blast-radius auto-connects to .rgbuilder/query.sock unless RGBUILDER_NO_QUERY_DAEMON=1

Rules of thumb

Index first — gql, blast-radius, metrics fail without discover.
Use -f json — stable schema_version fields; see json-api.md.
inspect takes a symbol only — no --class (use blast-radius for disambiguation).
slice --function is the method/function name, not the class name.
export --query uses filter syntax (name:Foo, type:Function, all) — not full GQL MATCH.
Deep analysis needs discover --with-cfg (and --with-taint for discover-time taint) (slice, inspect, taint).
Semantic search needs semantic index (separate from discover). Default code-daemon needs LFS ONNX weights from source; offline use --embedder vocab or --embedder hash. Fusion is on by default (--no-fusion to disable).
Profile discover — discover -v with RUST_LOG=profile=info for [profile] stage and centrality sub-phase timings (see analysis-architecture.md). Cold gates: cargo test --release --test cold_profile_gates -- --ignored (linux / metasfresh / kafka).
Dashboard is optional — only with --with-dashboard / serve when a human wants a UI; never required for structural answers.

On-disk artifacts for agents

After discover:

Path	Content
`.rgbuilder/graph.snapshot.bin`	Graph snapshot
`.rgbuilder/dashboard/manifest.json`	Counts, feature flags
`.rgbuilder/dashboard/migration_plan.json`	Migration export (with `--with-dashboard` and/or `--export-migration-hints`)
`.rgbuilder/dashboard/graph_payload.bin`	Columnar graph for dashboard WASM
`.rgbuilder/semantic_index.bin`	Opt-in semantic search index (`semantic index`)

Exit codes

Code	Meaning
`0`	Success
`1`	Policy violation (`check`, `blast-radius --policy-file`) or command error