rgctl for AI agents (USER TEMPLATE)

Copy this file into your own repository as root AGENTS.md if you want agents working on that codebase to prefer rgctl for structural questions.

Preferred (automated): install the agent pack instead of (or in addition to) pasting this file:
rgctl -r "$REPO" install --skill --with-commands --tools cursor,claude,codex,antigravity,agents
See Agent commands. This template is a fallback / complementary channel — skills remain the canonical runtime guidance.

Not for contributing to rgctl itself. Contributors: see the repository root AGENTS.md.

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

Installation: installation.md
Agent pack install: agent-commands.md
Full JSON reference: json-api.md · site
Copy-paste recipes: agent-recipes.md
Human walkthrough: user-guide.md
Docs hub: docs/README.md · site docs

Default for agents: spawn rgctl -f json subprocesses (or use foreground rgctl serve for repeated HTTP queries). Do not open the browser dashboard unless the user asks for a visual UI.

Install the agent pack once (limit --tools to the IDEs you use; default is all registry adapters):

rgctl -r "$REPO" install --skill --with-commands --tools cursor,claude,codex,antigravity,agents

Agent workflow

1. cd "$REPO" && rgctl discover .     # or rgctl -r PATH discover (no trailing . with -r)
2. rgctl -f json <command>            # compact facts on stdout
3. Parse schema_version + payload     # never scrape stderr for JSON

Artifacts live at {repo}/.rgctl/. Set REPO to the repository root:

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

Upgrading from an old daemon install: rgctl migrate-cache copies ~/.rgctl/cache/{name}/.rgctl/ into the repo (see installation.md).

High-value commands (low token cost)

Intent	Command
Full session (graph + CFG + dashboard + semantic)	`rgctl discover PATH --full` (queryable after stage 1; status in `.rgctl/pipeline_status.json`)
HTTP session (auto-pipeline)	`rgctl serve` — `GET /api/status`; `--no-pipeline` restores fail-fast
Inventory functions	`rgctl -f json gql --macro-name all_functions unused`
List communities	`rgctl -f json gql --macro-name all_communities unused`
Find symbol by pattern	`rgctl -f json gql "MATCH (n:Function) WHERE n.name LIKE 'Service' RETURN n LIMIT 20"`
Find by FQN (not `n.name`)	`rgctl -f json gql "MATCH (n:Class) WHERE n.qualified_name = 'com.example.Foo' RETURN n"`
Community members	`rgctl -f json gql "MATCH (f:Function) WHERE f.community_id = '12' RETURN f LIMIT 20"`
Natural-language function search	`rgctl semantic index` then `rgctl -f json semantic query "checkout flow" --limit 10`
Community semantic search	`rgctl -f json semantic query "checkout" --scope community --limit 10`
Impact before editing	`rgctl -f json blast-radius <Symbol> [--depth N]`
Architectural hotspots	`rgctl -f json metrics --pagerank`
Call neighborhood	`rgctl -f json gql "MATCH (a:Function)-[:CALLS*1..3]->(b:Function) RETURN a,b LIMIT 50"`
Doc headings / cross-links	`discover` indexes `.md` / `.mdx` by default; GQL on `:Module` with `kind=heading` and `REFERENCES` — see markdown-context.md
Obsidian vault from docs	`rgctl -r "$REPO" discover -l markdown` then `export --export-format obsidian --export-output "$REPO/vault" --query all` — see markdown-context.md
Doc section semantic search	`rgctl semantic index --scope docs --embedder hash` then `rgctl -f json semantic query "checkout flow" --scope docs --limit 10` (query scope does not filter — index must be doc-scoped)
Hybrid CPG status / CALL / PDG / slice	`rgctl -f json cpg status` then `cpg function\|calls\|pdg\|slice` (needs `discover --with-cfg` for PDG/slice)
Field mutations (cart / DTO safety)	`rgctl -f json cpg mutations --type ShoppingCart --exclude-ctors` (needs `--with-cfg`)
Data flows / slice (CPG)	`rgctl -f json cpg flows FILE --line N --variable V --function F [--direction forward\|backward] [--with-alias]`
Loop-carried DFG tags	`rgctl discover . --with-cfg --with-dfg-loops`
AST skeleton	`rgctl discover --with-ast-skeleton` then `rgctl -f json cpg ast <Symbol>`
CPG export	`rgctl cpg export --format graphson --output cpg.json [--path-contains src/]`
Migration plan	`rgctl discover . --with-cfg --with-security --with-taint --with-dashboard --with-harmonic --export-migration-hints` then read `.rgctl/migration_plan.json`
CI gate on changes	`rgctl -f json check --policy-file policy.json` (exit 1 = violations)
Temporal PR gate	`rgctl -f json pr-check --policy-file rgctl-pr-policy.json --base-artifact .rgctl-base --base-ref origin/main --head-ref HEAD --strict`
Check temporal bridge	`rgctl -f json check --temporal --policy-file policy.json --base-ref origin/main --head-ref HEAD`
Incremental file index	`rgctl discover --files src/foo.rs,src/bar.rs` (requires existing `.rgctl/` snapshot)
Kantra migration rules	`rgctl discover . --with-kantra`

Repeated queries in one session

Option A — CLI subprocess (default for agents):

export REPO=/path/to/repo
rgctl -r "$REPO" -f json gql 'MATCH (n:Function) RETURN n LIMIT 5'
rgctl -r "$REPO" -f json blast-radius ShoppingCartService

Option B — HTTP (one long-lived process):

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

See http-api.md.

Rules of thumb

Artifacts — always {repo}/.rgctl/ after discover. Add .rgctl/ to .gitignore.
Index first — gql, blast-radius, metrics fail without discover.
Discover target — cd repo && rgctl discover . or rgctl -r PATH discover (no trailing . with -r).
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).
Semantic search needs semantic index (separate from discover). Default embedder is vocab.
Dashboard is optional — only when a human wants a UI.
Markdown docs — indexed on discover; see markdown-context.md.

On-disk artifacts

After discover, under {repo}/.rgctl/: graph.snapshot.bin, optional semantic_index.bin, dashboard payloads when enabled.

Exit codes

Code	Meaning
`0`	Success
`1`	Policy violation or command error