KGF-aware token pattern search, structural queries, and vector similarity search.
When to Use
- User asks to find specific code patterns (e.g. "nested for loops", "pub fn without docs")
- User asks "where is this function used?" or "find all pub structs"
- User wants structural search — not regex on raw text, but token-level matching
- User asks for semantic code search ("find functions that parse configuration")
- User wants to find proxy functions, long functions, or functions with many params
- Replaces manual grep/ripgrep for code-aware searches
- Use instead of Explore agent for targeted codebase queries
Token Pattern Search
Patterns are space-separated token matchers. KGF aliases resolve automatically
(e.g. pub → KW_pub), so you write natural code keywords:
# Find all pub fn declarations
indexion grep "pub fn *" src/
# Find pub struct definitions
indexion grep "pub struct *" src/
# Nested for loops (O(n²) candidates)
indexion grep "for ... for" src/
# Functions named "sort"
indexion grep "fn Ident:sort" src/
# Any token except pub, followed by fn
indexion grep "!pub fn" src/
# Using raw KGF token kinds also works
indexion grep "KW_pub KW_fn Ident" src/
Pattern Syntax
| Pattern | Meaning |
|---|---|
pub |
Match keyword (auto-alias → KW_pub) |
KW_fn |
Match token kind exactly |
Ident:foo |
Match kind and text |
* |
Match any single token |
... |
Match zero or more tokens (non-greedy) |
!pub |
Negation — any token except this kind |
(, ), {, -> |
Punctuation aliases |
Aliases are auto-generated from KGF specs — not hardcoded. Works for all KGF-supported languages.
Semantic Queries
Structural analysis beyond token patterns:
# Find proxy functions (wrappers that just delegate)
indexion grep --semantic=proxy src/
# Find long functions (30+ lines)
indexion grep --semantic=long:30 src/
# Find short functions (3 lines or less)
indexion grep --semantic=short:3 src/
# Find functions with 4+ parameters
indexion grep --semantic=params-gte:4 src/
# Find functions by name substring
indexion grep --semantic=name:sort src/
# Find undocumented pub declarations (also available as --undocumented)
indexion grep --undocumented src/
indexion grep --semantic=undocumented src/
Vector Similarity Search
Find code by natural language description using TF-IDF embeddings
(shared infrastructure with digest):
# Find functions related to "parse JSON configuration"
indexion grep --semantic="similar:parse JSON configuration" src/
# Find tokenization-related code
indexion grep --semantic="similar:tokenize source code into tokens" src/
# Find error handling patterns
indexion grep --semantic="similar:handle error and return" src/
Results are ranked by cosine similarity score.
Output Control
# File paths only
indexion grep --files "pub fn *" src/
# Match count per file
indexion grep --count "pub fn *" src/
# Context lines around matches
indexion grep --context=3 "for ... for" src/
# Include/exclude patterns
indexion grep --include='*.mbt' --exclude='*_test.mbt' "pub fn *" src/
Options
| Option | Default | Description |
|---|---|---|
--semantic=QUERY |
— | Semantic query (see above) |
--undocumented |
false | Find pub declarations without doc comments |
--files |
false | Show matching file paths only |
--count |
false | Show match count per file only |
--context=N |
0 | Lines of context around matches |
--include=GLOB |
— | Include file pattern (repeatable) |
--exclude=GLOB |
— | Exclude file pattern (repeatable) |
--specs-dir=DIR |
kgfs | KGF specs directory |
Relationship to Other Commands
| Command | Purpose | When to use |
|---|---|---|
grep |
Find specific patterns/functions | "Find all nested for loops" |
explore |
File-level similarity matrix | "What files are similar?" |
plan refactor |
Actionable refactoring plan | "What duplicates should I fix?" |
plan unwrap |
Proxy function detection + auto-fix | "Remove unnecessary wrappers" |
digest query |
Purpose-based function index | "Find function that handles X" (requires build step) |
grep --semantic=proxy overlaps with plan unwrap in detection, but plan unwrap
adds auto-fix capability. Use grep for quick discovery, plan unwrap for action.
grep --semantic=similar:... overlaps with digest query but requires no build step.
digest is better for repeated queries on large codebases (cached index).
Dogfooding Workflow
# After writing new code, check for patterns that need attention:
# 1. Find potential O(n²) sorts (nested loops)
indexion grep "for ... for" src/
# 2. Check for undocumented public API
indexion grep --undocumented src/
# 3. Find proxy functions to consider unwrapping
indexion grep --semantic=proxy src/
# 4. Find overly long functions
indexion grep --semantic=long:50 src/
# 5. Search for specific refactoring targets by similarity
indexion grep --semantic="similar:extract substring" src/
# 6. Trace all references to a type before moving it
indexion grep "TypeIdent:TfidfEmbeddingProvider" src/
# 7. Find all sort-related functions across the codebase
indexion grep --semantic=name:sort src/
# 8. Verify a refactoring didn't leave orphan references
indexion grep "Ident:old_function_name" src/ cmd/indexion/
Dogfooding Lessons
- Use instead of Explore agent:
grep "TypeIdent:X"is faster and more precise than spawning an agent to search for a type definition. - Alias resolution is automatic: You don't need to know that
pubmaps toKW_pub— just write the keyword as it appears in source code. ...is non-greedy:for ... forfinds the closest pair of for loops, not the furthest. This is usually what you want for finding nesting.- Vector search quality:
--semantic="similar:..."works best with descriptive phrases. "parse JSON configuration" works better than just "json". - Combine with plan refactor: Use
grep --semantic=name:Xto find all instances before consolidating, thenplan refactorto verify they're gone.