RepoQL: When and How
RepoQL is a local knowledge graph for repositories. It indexes code structure, enabling exploration without reading every file.
When to Use RepoQL
Use RepoQL when:
- •Exploring unfamiliar codebases (Inventory -> Locate -> Inspect)
- •Finding where something is implemented (Locate intent)
- •Understanding code structure without reading every file
- •Searching semantically ("how does auth work?")
- •Aggregating info (count functions, find patterns)
- •Fetching content with token budget awareness (read tool)
Use regular file reads when:
- •You know exactly what file you need
- •Making edits (RepoQL is read-only)
- •Working with files RepoQL doesn't index
The Explore Workflow
Match your intent to your knowledge state:
| Intent | Question | Result |
|---|---|---|
| Inventory | "What exists?" | Broad discovery of files/structure |
| Locate | "Where is X?" | Ranked results with snippets |
| Inspect | "Show me structure" | Detailed view with line numbers |
| Explain | "How does X work?" | LLM-synthesized answer |
Typical progression:
- •Inventory a scope to understand what's there
- •Locate specific concepts with keywords
- •Inspect relevant files for structure
- •Explain complex logic when needed
Tools Summary
| Tool | Use Case |
|---|---|
repoql_explore | Discovery and understanding (start here) |
repoql_query | SQL aggregation and filtering |
repoql_read | Fetch content with token budget |
repoql_import | Add external repositories |
Token Budgets
Budget = tokens you want to spend on the response.
| Intent | Typical Budget |
|---|---|
| Inventory | 800-2000 |
| Locate | 1000-2000 |
| Inspect | 2000-5000 |
| Explain | 1000-3000 |
Higher budget = richer detail. Start small, increase if needed.