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

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