diff --git a/CLAUDE.md b/CLAUDE.md
index 4ceae29..a0f9960 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,25 @@
 # Claude Instructions for WLED Screen Controller
 
+## CRITICAL: Use ast-index for Code Search
+
+**Always use `ast-index` as the PRIMARY code search tool.** It is 17-69x faster than grep and returns structured, accurate results.
+
+- **Use ast-index first** for: finding classes, symbols, usages, implementations, files, callers, hierarchy
+- **Fall back to Grep only** for: regex patterns, string literals inside code, comment content, or when ast-index returns empty results
+- Run `ast-index update` if the index feels stale after many file changes
+- Run `ast-index rebuild` if the index is missing or corrupted
+
+Common commands:
+```bash
+ast-index search "Query"              # Universal search
+ast-index symbol "Name"               # Find symbol definitions
+ast-index usages "Symbol"             # Find all usages
+ast-index class "Name"                # Find class/interface
+ast-index implementations "Parent"    # Find implementations
+ast-index outline "path/to/file"      # Show file structure
+ast-index callers "funcName"          # Find call sites
+```
+
 ## CRITICAL: Git Commit and Push Policy
 
 **🚨 NEVER CREATE COMMITS WITHOUT EXPLICIT USER APPROVAL 🚨**