godgrep

godgrep

Routes codebase search tasks to the right tool based on intent.

Tool Routing

Intent	Primary tool	Also consider
Keyword / symbol search (exact identifier known)	mcp__plugin_ora_fff__grep	LSP for definitions
Multi-pattern OR — naming variants of one identifier	mcp__plugin_ora_fff__multi_grep	sequential mcp__plugin_ora_fff__grep calls
File discovery (by name)	mcp__plugin_ora_fff__find_files	mcp__plugin_ora_fff__grep for content matches
Concept / "how does X work" / "where is Y handled" (no identifier yet)	mcp__plugin_ora_morph__codebase_search	fall back to find_files + fff__grep + Read only if morph misses
Trace a feature end-to-end	mcp__plugin_ora_morph__codebase_search for the initial map	mcp__plugin_ora_fff__grep to verify specific call sites
Find all usages of X	LSP find-references	mcp__plugin_ora_fff__grep
Find a specific symbol	LSP go-to-definition	mcp__plugin_ora_fff__grep
Structural code patterns	ast-grep	mcp__plugin_ora_fff__grep as fallback
Outside git index / fallback	shell grep / find	last resort, after fff
Git history / blame	Bash (git log/blame)	—

When the question is a single broad concept, one mcp__plugin_ora_morph__codebase_search call replaces multi-angle parallelization. Split into 2-3 parallel angles only when the work is multiple independent identifier-based searches (e.g. "find callers of X and definitions of Y in one pass").

Anti-pattern: shotgun OR-grep for features

Do not enumerate guesses for one feature with a long OR-pattern — synonyms get missed and the output drowns in noise:

# Shotgun-grep — fragile, no signal
grep -r "FreeGift|ProgressBar|GiftModal|BuyXGetY|percentOff|fixedOff|salepify"
grep -r "appUpdate|checkAppUpdate|versionCheck|setAppUpdateHandler|needUpdate"

Instead: skim README/dir structure to learn the feature's actual name, pick one specific term, grep for it, Read the top hit, and follow references. multi_grep is for naming variants of one identifier (e.g. ['ActorAuth', 'PopulatedActorAuth', 'actor_auth']), not for guessing a feature's vocabulary.

Morph codebase_search — default for semantic/concept queries

mcp__plugin_ora_morph__codebase_search runs a Morph WarpGrep subagent that parallel-greps and reads files, returning a synthesized answer. Reach for it first when the question is shaped like "how does X work", "where is Y handled", "what wires Z together", "find all the places that do W". One morph call beats 4-8 fff__grep + Read turns on these shapes.

• Use when the question is conceptual / semantic / "find X-related code" and you don't have a single exact identifier to grep. Why: morph parallelizes the grep + read + summarize loop the calling agent would otherwise do serially; cuts latency and turn count substantially.
• Do not use when you have a concrete identifier — fff__grep is faster, exhaustive, and returns exact file:line hits in one call.
• Trust citations, verify conclusions — morph's file:line references point to real code locations, but its synthesis (what that code does, how it fits the question) can be wrong. When the answer is load-bearing, Read the cited locations and confirm morph's interpretation before relaying.

ast-grep

Structural code search using Abstract Syntax Tree patterns. Matches code by structure, not text.

Pattern Search

ast-grep run --pattern '<pattern>' --lang <lang> <path>

# Find all console.log calls
ast-grep run --pattern 'console.log($ARG)' --lang javascript .

# Find class declarations
ast-grep run --pattern 'class $NAME' --lang python /path/to/project

Complex Rules

Inline YAML (quick iterations, no temp files):

ast-grep scan --inline-rules "<yaml>" <path>

# Find async functions containing await
ast-grep scan --inline-rules "id: async-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" /path/to/project

Rule file (recommended for complex rules):

# Write rule to a temp file, then scan
ast-grep scan --rule /tmp/my_rule.yml /path/to/project

AST Inspection

ast-grep run --pattern '<code>' --lang <lang> --debug-query=cst

Use --debug-query=cst to dump the concrete syntax tree and find correct kind values when rules do not match. Available formats: cst (all nodes), ast (named nodes only), pattern (how ast-grep interprets your pattern).

Critical Rules

• ALWAYS use stopBy: end for relational rules (inside, has) -- without it, search stops at the first non-matching node instead of traversing the full subtree:

has:
  pattern: await $EXPR
  stopBy: end # required for deep traversal

• Escape metavariables in shell: use \$VAR in double-quoted strings, or '$VAR' in single-quoted strings
• Start simple (pattern first), add kind + relational rules only when needed
• Use all/any/not to compose complex structural queries

Reference: references/ast-grep/ast-grep.md for full guide, references/ast-grep/rule_reference.md for YAML rule syntax.

---

Do not reach for ast-grep when mcp__plugin_ora_fff__grep/mcp__plugin_ora_fff__find_files/LSP suffice — it is slower and consumes more resources. Escalate to ast-grep only when the search requires understanding code structure, not just text.