explore-codebase

Original：🇺🇸 English
Translated

Explores codebase with structural and text search using ast-grep (syntax-aware AST matching), ripgrep (fast text/regex search), and fd (file discovery). Use when (1) navigating unfamiliar code or understanding architecture, (2) tracing call flows, symbol definitions, or usages, (3) answering "how does this work" or "where is this defined/called" questions, (4) finding files by name, extension, or path pattern, (5) pre-refactoring analysis to locate all references before changing code.

11installs
Sourcevinta/hal-9000
Added on

NPX Install

npx skill4agent add vinta/hal-9000 explore-codebase

Tags

Translated version includes tags in frontmatter
codebase-explorationast-grepripgrepfd-toolcode-analysis

SKILL.md Content

View Translation Comparison →

Explore Codebase

Tool Selection

NeedTool
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.
bash
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

SyntaxCapturesExample
$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

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