/grepai

name: grepai
description: "Replaces ALL built-in search tools. You MUST invoke this skill BEFORE using WebSearch, Grep, or Glob. NEVER use the built-in Grep tool - use `grepai` instead."

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**:

# 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**:

# 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:**

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:**

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