ViperJuice Smart Search
Decision Tree: Pick the Right Tool
| Goal | Tool | Pattern Example |
|---|---|---|
| Find a file by name | Glob | **/{name}* or **/*.{ext} |
| Find where a function/class is defined | Grep | "(function|class|def|const)\\s+NAME" |
| Find all usages of a symbol | Grep with --type |
"NAME" + type: "ts" |
| Find a file matching a vague description | Explore agent | Natural language prompt |
| Understand how a module works | Explore agent | Better than 10 Grep calls |
Rule of thumb: If you'd need 4+ Grep calls to answer a question, use an Explore agent instead.
Ripgrep Escaping Rules
The Grep tool uses ripgrep, NOT standard grep. These characters need escaping for literal matches:
| Character | Meaning in Regex | Escape for Literal |
|---|---|---|
{ } |
Repetition {n,m} |
\{ \} |
( ) |
Capture group | \( \) |
[ ] |
Character class | \[ \] |
| |
Alternation (OR) | \\| |
. |
Any character | \. |
* |
Zero or more | \* |
+ |
One or more | \+ |
? |
Optional | \? |
^ |
Start of line | \^ |
$ |
End of line | \$ |
The #1 mistake: Searching for interface{} in Go code without escaping braces. Correct: interface\{\}
Search Planning Rule
Before your second Grep/Glob call on the same topic, STOP and diagnose:
- Wrong pattern? → Check escaping rules above, verify regex syntax
- Wrong scope? → Add
path:to narrow, ortype:to filter by language - Wrong tool? → Maybe Glob for filenames, Explore for broad understanding
- Doesn't exist? → Accept that the thing may not exist; tell the user
Do NOT: run 3+ similar searches changing one letter at a time. That's thrashing.
Useful Flag Combinations
type: "ts"— filter to TypeScript files only (also:py,js,rust,go,java)-i: true— case-insensitive (use when unsure of casing conventions)output_mode: "content"withcontext: 3— show matching lines with 3 lines of surrounding contextoutput_mode: "count"— check if pattern exists at all before reading matchesoutput_mode: "files_with_matches"— just get file paths (default, good for scoping)head_limit: 10— stop after 10 results to avoid overwhelming output
Common Mistakes
- Forgetting file type filter: Searching entire repo when you know the language
- Too-broad patterns:
"error"matches thousands of lines. Be specific:"error TS\\d+" - No context lines: Finding a match but not understanding it. Use
-C 3to see surrounding code - Searching in node_modules/build artifacts: Use
type:filter or narrowpath: - Using Grep to find files by name: That's what Glob is for
Reference
See references/ripgrep-patterns.md for a cheatsheet of common code patterns and their correct ripgrep syntax.