Search Tool Hierarchy
Use the most token-efficient search tool for each query type.
Decision Tree
Query Type? ├── STRUCTURAL (code patterns) │ → AST-grep (~50 tokens output) │ Examples: "def foo", "class Bar", "import X", "@decorator" │ ├── SEMANTIC (conceptual questions) │ → LEANN (~100 tokens if path-only) │ Examples: "how does auth work", "find error handling patterns" │ ├── LITERAL (exact identifiers) │ → Grep (variable output) │ Examples: "TemporalMemory", "check_evocation", regex patterns │ └── FULL CONTEXT (need complete understanding) → Read (1500+ tokens) Last resort after finding the right file
Token Efficiency Comparison
| Tool | Output Size | Best For |
|---|---|---|
| AST-grep | ~50 tokens | Function/class definitions, imports, decorators |
| LEANN | ~100 tokens | Conceptual questions, architecture, patterns |
| Grep | ~200-2000 | Exact identifiers, regex, file paths |
| Read | ~1500+ | Full understanding after finding the file |
Hook Enforcement
The grep-to-leann.sh hook automatically:
- Detects query type (structural/semantic/literal)
- Blocks and suggests AST-grep for structural queries
- Blocks and suggests LEANN for semantic queries
- Allows literal patterns through to Grep
DO
- Start with AST-grep for code structure questions
- Use LEANN for "how does X work" questions
- Use Grep only for exact identifier matches
- Read files only after finding them via search
DON'T
- Use Grep for conceptual questions (returns nothing)
- Read files before knowing which ones are relevant
- Use Read when AST-grep would give file:line
- Ignore hook suggestions
Examples
bash# STRUCTURAL → AST-grep ast-grep --pattern "async def $FUNC($$$):" --lang python # SEMANTIC → LEANN leann search opc-dev "how does authentication work" --top-k 3 # LITERAL → Grep Grep pattern="check_evocation" path=opc/scripts # FULL CONTEXT → Read (after finding file) Read file_path=opc/scripts/z3_erotetic.py
Optimal Flow
1. AST-grep: "Find async functions" → 3 file:line matches 2. Read: Top match only → Full understanding 3. Skip: 4 irrelevant files → 6000 tokens saved
