Repository Planning Graph

Enable and query grepai's Repository Planning Graph (RPG), a feature-level graph of files, symbols and chunks, from the CLI or MCP.

The Repository Planning Graph (RPG) groups your code into a feature hierarchy (areas, categories, subcategories) and links it to files, symbols, vector chunks and call dependencies. Use it when search finds relevant code and you also want to know which feature it belongs to and what sits around it.

Prerequisites

RPG is disabled by default. Enable it in .grepai/config.yaml (the grepai init --ui wizard also offers it):

rpg:
  enabled: true

Then build the index:

grepai index     # one-time build, then exit
# or
grepai watch     # same initial build, then keeps the graph up to date

The graph is stored in .grepai/rpg.gob. It is built from the symbol index used by grepai trace and from the vector chunks, so it covers the languages listed in trace.enabled_languages.

Quick check:

grepai rpg search "command line search flow"

If RPG is disabled or the graph is empty, the command fails with RPG is not enabled or index is empty. If the graph was written by an incompatible version, it fails with RPG index is outdated; run 'grepai watch' to rebuild (grepai index rebuilds it too).

Search RPG Nodes

grepai rpg search finds nodes whose feature labels or symbol names share words with your query. Scoring is word overlap (Jaccard), not embeddings, so use words that appear in feature or symbol names.

grepai rpg search "command line search flow"
grepai rpg search "command line search flow" --kinds symbol,file --scope cli --limit 5
grepai rpg search "command line search flow" --json

Flag	Description	Default
`--kinds`	Comma-separated node kinds: `area`, `category`, `subcategory`, `file`, `symbol`, `chunk`	`symbol`
`--scope`	Keep only nodes whose feature path starts with this prefix, such as `cli` or `rpg/query`	none
`--limit`, `-n`	Maximum number of results	`10`
`--json`	JSON output
`--toon`, `-t`	Token-efficient TOON output

Each result shows the node name, kind, score, node ID, feature path and file location. Pass the node ID to fetch or explore.

Node IDs follow this format:

Kind	ID format	Example
Symbol	`sym:<path>:<name>` or `sym:<path>:<Receiver>.<name>`	`sym:cli/search.go:runSearch`
File	`file:<path>`	`file:cli/search.go`
Area	`area:<name>`
Category	`cat:<area>/<name>`
Subcategory	`subcat:<parent>/<name>`
Chunk	`chunk:<chunk-id>`

Fetch Node Context

fetch shows one node with its hierarchy and edges:

grepai rpg fetch "sym:cli/search.go:runSearch"
grepai rpg fetch "sym:cli/search.go:runSearch" --json

The text output lists the node ID, kind, symbol, feature, feature path, file and line, then the number of parents, children, incoming edges and outgoing edges, followed by a code preview when one is available. Use --json or --toon to get the full parent, child and edge lists.

Explore Neighborhoods

explore walks the graph breadth-first from a starting node:

grepai rpg explore "sym:cli/search.go:runSearch"
grepai rpg explore "sym:cli/search.go:runSearch" --direction forward --depth 1 --edge-types invokes --json

Flag	Description	Default
`--direction`	`forward` (outgoing edges), `reverse` (incoming edges) or `both`	`both`
`--depth`, `-d`	Maximum traversal depth	`2`
`--edge-types`	Comma-separated edge types to follow (see below)	all
`--limit`, `-n`	Maximum number of nodes returned	`100`
`--json`	JSON output
`--toon`, `-t`	Token-efficient TOON output

Edge types:

Edge type	Meaning
`feature_parent`	Hierarchy node to child node (area, category, subcategory, file)
`contains`	File to the symbols it defines
`invokes`	Symbol calls symbol
`imports`	File imports file or package
`maps_to_chunk`	Symbol to the vector chunk that holds its code
`semantic_sim`	Symbols with similar features or call patterns

Configuration

All keys live under rpg: in .grepai/config.yaml. Defaults:

Key	Default	Description
`enabled`	`false`	Build and maintain the graph.
`feature_mode`	`local`	`local` derives verb-object feature labels (such as `validate token`) from symbol names with heuristics. `llm` and `hybrid` ask an LLM instead (both behave the same today) and fall back to `local` on errors.
`llm_provider`	`ollama`	Label for the LLM backend. Requests use the OpenAI-compatible `/chat/completions` API.
`llm_endpoint`	`http://localhost:11434/v1`	Base URL of the OpenAI-compatible API.
`llm_model`	empty	Model name. If `llm_model` or `llm_endpoint` is empty, grepai uses `local`.
`llm_api_key`	empty	API key, if the endpoint needs one.
`llm_timeout_ms`	`8000`	Timeout per LLM request.
`drift_threshold`	`0.35`	During incremental updates, a file moves to a new place in the hierarchy only when its features change by at least this much (`0.0` to `1.0`).
`feature_group_strategy`	`sample`	When building `semantic_sim` edges, how oversized groups of similar symbols are reduced: `sample` (random sample) or `split` (by directory).

When RPG is enabled, grepai trace and grepai search results also show the feature path of each symbol or chunk.

MCP Parity

MCP clients get the same features as these tools:

grepai_rpg_search (query, scope, kinds, limit)
grepai_rpg_fetch (node_id)
grepai_rpg_explore (start_node_id, direction, depth, edge_types, limit)

Defaults match the CLI. The CLI uses positional arguments and --json/--toon; MCP tools take named parameters and a format parameter (json by default, or toon). See MCP Integration.