yoanbernabeu/grepai

CRITICAL: Tool Override for Semantic Searches

This skill REPLACES built-in Grep/Glob tools for semantic code exploration.

WRONG:

• Using built-in Grep to find "where authentication happens"
• Using built-in Glob to explore "error handling code"
• Searching by intent with regex patterns

CORRECT:

• Invoke this skill, then use grepai search "authentication flow" for semantic search
• Invoke this skill, then use grepai trace callers "FunctionName" for call graph
• Use built-in Grep/Glob ONLY for exact text matches (variable names, imports)

When to Invoke This Skill

Invoke this skill IMMEDIATELY when:

• User asks to find code by intent (e.g., "where is authentication handled?")
• User asks to understand what code does (e.g., "how does the indexer work?")
• User asks to explore functionality (e.g., "find error handling logic")
• You need to understand code relationships (e.g., "what calls this function?")
• User asks about implementation details (e.g., "how are vectors stored?")

DO NOT use built-in Grep/Glob for intent-based searches. Use grepai instead.

When to Use Built-in Tools

Use Grep/Glob ONLY for:

• Exact text matching: Grep "func NewIndexer" (find exact function name)
• Specific imports: Grep "import.*cobra" (find import statements)
• File patterns: Glob "**/*.go" (find files by extension)
• Variable references: Grep "configPath" (find exact variable name)

How to Use This Skill

Semantic Search

Use grepai search to find code by describing what it does:

bash
# Search with natural language (ALWAYS use English for best results)
grepai search "user authentication flow"
grepai search "error handling middleware"
grepai search "database connection pooling"
grepai search "API request validation"

# JSON output for AI agents (--compact saves ~80% tokens)
grepai search "authentication flow" --json --compact

# Limit results
grepai search "error handling" -n 5

Call Graph Tracing

Use grepai trace to understand function relationships:

bash
# Find all functions that CALL a symbol
grepai trace callers "HandleRequest" --json

# Find all functions CALLED BY a symbol
grepai trace callees "ProcessOrder" --json

# Build complete call graph (both directions)
grepai trace graph "ValidateToken" --depth 3 --json

Query Best Practices

Do:

bash
grepai search "How are file chunks created and stored?"
grepai search "Vector embedding generation process"
grepai search "Configuration loading and validation"
grepai trace callers "Search" --json

Don't:

bash
grepai search "func"           # Too vague
grepai search "error"          # Too generic
grepai search "HandleRequest"  # Use Grep for exact matches

Recommended Workflow

1. Start with grepai search to find relevant code semantically
2. Use grepai trace to understand function relationships
3. Use Read tool to examine files from search results
4. Use Grep only for exact string searches if needed

Fallback

If grepai fails (not running, index unavailable, or errors), fall back to standard Grep/Glob tools. Common issues:

• Index not built: Run grepai watch to build/update the index
• Embedder not available: Check that Ollama is running or OpenAI API key is set

Keywords

semantic search, code search, natural language search, find code, explore codebase, call graph, callers, callees, function relationships, code understanding, intent search, grep replacement, code exploration