Index once (
discover), then ask callers, blast radius, control/data-flow slices, clones, communities, and PR call-path deltas — compact deterministic JSON for agents, not grepping the tree.
What the R stands for: Rust · Reachability · Rich graph (30+ typed relations, Hybrid CPG, mmap snapshots).
| Dimension | Without (grep / dump files) | With rgctl |
|---|---|---|
| Tool calls for “who calls X transitively?” | Many greps + ad-hoc file reads | 1–2 (discover once, then callers / blast-radius) |
| Context tokens | Whole files / search dumps into the prompt | Compact -f json payloads (schema_version) |
| Transitive reachability & PR review | Easy to miss or hallucinate | Precomputed SCC reachability, blast-radius, review paths |
| Control & data flow | Manual line-by-line tracing | Statement-level slice, cpg flows, inspect (CFG / PDG / dominance) |
| Error recovery for agents | Raw exit codes or unstructured stderr | Structured JSON error envelope (error_code, candidates, recovery_command) |
Cold discover and zero-hydration mmap queries on real-world repositories (see AGENTS.md Gate A/B and profile notes):
- Linux kernel (~71k C files): cold discover in ~134 s
- metasfresh (Java EE
--fullwith CFG/CPG + analytics): ~25.7 s - Node.js (
test/JS--with-cfg): ~4.8 s - Kubernetes, LLVM, Roslyn, rustc, Home Assistant, Magento 2, Discourse, VS Code, JetBrains/kotlin, Gradle
- 14 Tier-1 languages + Markdown/ERB, backed by memory-mapped columnar snapshots (
graph.snapshot.bin) and incremental updates (rgctl update/rgctl serve --watch).
rgctl discover . --with-cfg
rgctl -f json status
rgctl -f json find --type function --limit 20
rgctl -f json callers MyService --depth 1
rgctl -f json blast-radius MyService --class OrderHandler
rgctl -f json review paths --base-ref origin/main --head-ref HEAD
# Install skills + /rgctl:review slash command into your coding agent
rgctl install --skill --tools cursor,claude,codex,antigravity,agentsuser-guide-cli.mp4
One-line release binary (macOS / Linux):
curl -fsSL https://shaaf.dev/rgctl/install.sh | sh
rgctl --versionInstalls to ${RGCTL_INSTALL_DIR:-$HOME/.local/bin}. Or download a prebuilt archive from GitHub Releases and place rgctl on your PATH.
Or build from source (Rust 1.85+):
git clone https://github.com/sshaaf/rgctl.git
cd rgctl
cargo build --release --locked --bin rgctl
# If ort/ONNX link fails on your platform: add --no-default-features
export PATH="$PWD/target/release:$PATH"Details, PATH setup, and troubleshooting: Installation.
cd rgctl-tests/ecommerce-java # or pass -r <PATH> from anywhere
rgctl discover . --with-cfg
rgctl -f json status # shows graph, CFG/CPG, semantic & skill readinessArtifacts land in {repo}/.rgctl/. Run rgctl update (or rgctl serve --watch) for fast incremental updates after code edits.
# Inventory & symbol lookup
rgctl -f json inventory --by type
rgctl -f json find --type function --package com.ecommerce.service --limit 10
# Callers, callees & typed relations
rgctl -f json callers ProductService --depth 1
rgctl -f json relations --edge calls --limit 20
# Impact before you edit a symbol (disambiguate overloads with --file / --class / --line)
rgctl -f json blast-radius processOrder --class OrderService
# Control-flow, PDG & program slicing (requires discover --with-cfg)
rgctl -f json inspect OrderService::createOrder cfg
rgctl -f json slice --function OrderService::createOrder --line 42
# Duplicate & structural clone detection
rgctl -f json clones --mode exact --min-loc 5 --exclude test
# PR call-path impact vs base branch
rgctl -f json review paths --base-ref origin/main --head-ref HEAD- For agents & scripts: Always pass
-f json(orRGCTL_FORMAT=json). Both data and structured errors (ok: false,error_code,candidates,recovery_command) are emitted onstdout(JSON API). Never scrapestderr. - For humans in a terminal: Default text output formats symbols as
kind name file:linewhenstdoutis a TTY and stays pipe-friendly (1column) when piped.
Install the bundled agent pack (rgctl + rgctl-review skills and the /rgctl:review slash command) into your IDE or CLI agent:
rgctl install --skill --tools cursor,claude,codex,antigravity,agentsrgctlskill: Routes natural-language architecture, impact, slicing, clone, community, and migration questions to deterministicrgctl -f jsoncommands.rgctl-reviewskill (/rgctl:review): Runs a local PR/branch structural review (review paths,review check, blast radius) and writesREVIEW_REPORT.md+ a four-section verdict without posting to GitHub/GitLab.
See the Agent pack guide. For your application repo, you can also copy USER_AGENTS_TEMPLATE.md into AGENTS.md.
Commands are organized into six groups (rgctl --help):
| Group | You need… | Command |
|---|---|---|
| Lifecycle | Index repo, incremental refresh, readiness check | discover, update, status, serve --watch |
| Query | Find symbols, callers, callees, typed edges, GQL | find, inventory, callers, callees, relations, gql |
| Analysis | Upstream impact (“what breaks if I edit X?”) | blast-radius |
| Analysis | CFG / PDG / dominance / backward & forward slices | slice, inspect, cpg (needs discover --with-cfg) |
| Analysis | Exact (Type-1), bloom & SESE/1-WL fragment clones | clones (--mode exact | bloom | fragment) |
| Analysis | Centrality hotspots & label-propagation clusters | metrics, communities |
| Analysis | Natural-language search over functions or docs | semantic (index, query) |
| Security | OSV advisories, lockfile deps, taint & OpenVEX | security (vuln triage, vuln analyze, deps check, taint) |
| Policy & PRs | PR call-path deltas & CI blast-radius gates | review paths, review check (pr-check), check |
| Policy & Migration | Konveyor Kantra rules, custom YAML rules, roadmap | discover --with-kantra, kantra, rules, discover --export-migration-hints |
| Meta & Export | Snapshot diff, subgraph export, browser UI | diff, export (JSON, GraphML, Mermaid, Obsidian), serve |
- Step-by-step feature guides (CoolStore): docs/guides
- Concepts & architecture overview: Introduction
- Full CLI walkthrough (ecommerce-java): User Guide
14 Tier-1 tree-sitter plugins: C, C++, C#, Go, Groovy, Java, JavaScript, Kotlin, PHP, Puppet, Python, Ruby, Rust, TypeScript, plus ERB and Markdown (.md / .mdx document context graph).
Each language plugin’s AST coverage is tracked in crates/rgctl-lang-*/{id}-ast-coverage.json and rendered at shaaf.dev/rgctl/docs/languages/ — see Languages.
We welcome contributors across four tracks — see CONTRIBUTING.md to get started:
- Language Plugins & AST Coverage: Add or deepen tree-sitter extractors (contributor-checklist.md, language-testing-guide.md).
- Declarative Taint & Kantra Rules: Expand security source/sink/sanitizer rules and migration rule packs (vulnerability-and-osv-analysis.md).
- Agent Host Adapters & Skills: Improve agent workflows, slash commands, and IDE host adapters (agent-skill.md).
- Graph & CPG Algorithms: Work on CSR projections, reachability, dominance, SESE clone detection, and columnar storage (analysis-architecture.md, graph-storage-architecture.md).
| Doc | For |
|---|---|
| Installation | One-line install, build from source, PATH setup |
| Introduction | What / why / capability map |
| Guides | 19 step-by-step feature guides |
| User Guide | ecommerce-java + full CLI reference |
| JSON API | -f json schemas, schema_version, error envelopes |
| Docs index | Complete documentation map |
| AGENTS.md | Performance rules & cold gates for contributing to this repo |
| CONTRIBUTING.md | Contributor tracks, dev setup, test matrix |
| Latest release · Unreleased | Release notes & upcoming changelog |
MIT — see LICENSE.