Tool

explain

Delegate the understanding. explain reads widely inside the scope you give it, synthesises, and reports back with citations — so you get comprehension rather than raw text. Fire several in parallel across different areas when you are mapping something large.

explain question="which capabilities require the cloud service, and which work with no network at all?" keywords="embedding, reranker, inference, offline, lexical" uriGlob="file:///src/L1/engine/RepoQL.Engine.Embedding*/**" 200 matches · [2.9k tok | ready] The index, graph, lexical search and git operations are fully local; semantic quality and synthesis depend on cloud services but degrade gracefully. ... <Evidence> file:///src/L1/engine/RepoQL.Engine.Embedding/EmbeddingProvider.cs Composite embedding provider. One active provider at a time, swappable on lifecycle events (login/logout), cached in persistent Parquet storage. ...

Two hundred matches read, one answer returned, every claim carrying the file it came from. The evidence section is the point — you can check it rather than trust it.

Run it yourself

rql explain "how does the embedding cache work?" --glob "file:///src/cloud/**"

Or say it to your agent

“explain how the embedding cache works, and cite the code”

Parameters

ParameterWhat it does
questionrequiredWhat you want answered. Full sentences work best.
keywordsrequiredThe symbols, files, or terms-of-art to focus on. You almost always know these better than they can be inferred.
uriGloboptionalScope. Always set it — an unscoped explain will confidently answer a different question than the one you meant.
tokenBudgetoptionalRoom for the synthesised answer. It does not limit how much source gets read.

Good questions and bad ones

It rewards a scoped question with a real subject: how does JWT refresh work in AuthService, why does the payment processor use idempotency keys, what happens when an item is indexed, step by step. It does poorly with explain everything about authentication, or what does this service do with no scope — there is no way for it to know which half you meant.

Verify what matters

Every claim carries a citation for a reason. When the stakes are high, follow one back with read and check it against the code.

This page names what exists. The depth behind every name — the bounds, the failure modes, how they compose — ships inside the binary at help:///, and answers to explore and read exactly like your code does. Install it, and your agent has the manual.