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 '' --lang  

# 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 "" 

# 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 '' --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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trancong12102
• Source: trancong12102/agentskills
• License: MIT

Install and usage instructions live in the source repository linked above.