Explore Codebase

Tool Selection

Need	Tool
Structural patterns (functions, classes)	sg (ast-grep)
Text/regex patterns (strings, names)	rg (ripgrep)
File discovery by name/extension	fd

Decision flow: Find files first? fd → pipe to rg/sg. Syntax-aware match needed? sg. Fast text search? rg. Uncertain? Start with rg, escalate to sg if structure matters.

ast-grep Essentials

ast-grep is the least familiar tool -- key syntax summarized here. See references/ast-grep.md for language-specific patterns and YAML rule files.

sg -p 'PATTERN' -l LANG [PATH]
sg -p 'PATTERN' --has 'INNER' -l LANG       # Must contain
sg -p 'PATTERN' --not-has 'INNER' -l LANG   # Must not contain
sg -p 'PATTERN' --inside 'OUTER' -l LANG    # Must be within

Metavariables

Syntax	Captures	Example
$VAR	Single node	console.log($MSG)
$$$VAR	Zero or more nodes	function($$$ARGS) -- any arity
$_	Non-capturing	$_FUNC($_) -- match without capture

Rules: must be UPPERCASE, same name = same content ($A == $A matches x == x not x == y).

Examples

sg -p 'function $NAME($$$ARGS) { $$$ }' -l js
sg -p 'async function $NAME($$$) { $$$ }' --has 'await $EXPR' -l js
sg -p 'class $NAME extends $PARENT { $$$ }' -l ts
sg -p 'def $NAME($$$): $$$' -l py

ripgrep / fd Quick Reference

Standard CLI tools -- use references/ripgrep.md and references/fd.md for full flag tables.

rg PATTERN -t TYPE [PATH]         # Search by file type
rg -F 'LITERAL' -t TYPE           # Fixed string (no regex)
rg PATTERN -l                     # List matching files only
rg PATTERN -C 3                   # With context lines

fd -e EXT [PATH]                  # Find by extension
fd PATTERN [PATH]                 # Find by name regex
fd -e py | xargs rg 'pattern'    # Pipe fd into rg

Performance

• Narrow scope first: fd -e py src/ | xargs rg 'class.*Test'
• Always use type filters: rg PATTERN -t rust, sg -p 'PATTERN' -l rs
• Exclude artifacts: rg PATTERN -g '!node_modules' -g '!dist'