---
name: grepai-first
description: Search with GrepAI or Grep before opening any file for context; Read only when full content is needed
applies-to: all
---

# Context Lookup — GrepAI First

Before reading any file for context, search with GrepAI or Grep. Only open a file when you need its full content for editing or line-by-line review.

## Lookup table

| Goal | Tool |
|------|------|
| Find where a function is defined | `grepai_search` or `Grep` |
| Understand how a feature works | `grepai_search` |
| Find all callers of a function | `grepai_trace_callers` |
| Find what a function calls | `grepai_trace_callees` |
| Full file content needed (edit, review) | `Read` |
| Recent changes to a file | `git log`, then `Read` specific file |
| "What did we do with X?" | `grepai_search` over session logs |
| "How is Y configured?" | `grepai_search` before checking any specific file |

## Token cost rationale

Reading a 500-line file to find one function costs approximately 3,000 tokens. A targeted GrepAI or Grep search costs approximately 100 tokens and returns only the relevant lines. At scale, reading files for context without searching first wastes context window and increases latency.

Never open a large file to scan for context. Search first; read only if the search result is insufficient or if you need to edit the file.

## GrepAI specifics

- CLI: `D:/claudetools/grepai.exe search "query" --json -c -n 5`
- MCP tools: `grepai_search` (primary), `grepai_trace_callers`, `grepai_trace_callees`
- The GrepAI index covers session logs, skill files, and project docs with boosted relevance for `.claude/` content
- The watcher (scheduled task "GrepAI Watcher - claudetools") keeps the index current automatically

## Common search queries

```bash
# Find where a setting is configured
grepai_search "vault_path"

# Understand how the Syncro skill handles billing
grepai_search "timer_entry charge_timer"

# Find what we did with a specific client or feature
grepai_search "Cascades DMARC"

# Locate a function definition
Grep --pattern "fn collect_temps" --type rust
```