Codebase Search

Step 0: AST-Aware Search (jcodemunch MCP — Preferred)

Use this first. jcodemunch parses the actual AST of your codebase and indexes every symbol with its signature, docstring, and an AI-generated summary. This lets you find symbols by meaning, trace call graphs, and navigate large repos in seconds — far beyond what grep can do.

jcodemunch vs. grep — choose the right tool

One-time indexing (incremental — safe to re-run)

Before using any jcodemunch tool, index the workspace. The incremental: true flag re-indexes only changed files, so it's fast on subsequent runs.

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "index_folder",
  arguments: {
    path: "<absolute-path-to-workspace>",
    incremental: true
  }
)

Already indexed? Call list_repos to see all indexed repos. If your workspace appears, skip re-indexing. The repo parameter in every tool below is the repo name returned by list_repos or index_folder (usually the folder name, e.g. "my-project").

Decision tree — which tool to call

Need to...
├── Orient in an unknown codebase?
│   └── get_repo_outline(repo)
│       → directories, language breakdown, symbol counts
│
├── Find a function/class/type by name or description?
│   └── search_symbols(repo, query, kind?)
│       → ranked matches with signatures + summaries
│       kind options: "function" | "class" | "method" | "constant" | "type"
│
├── Where is symbol X called / referenced?
│   └── find_references(repo, identifier)
│       → all files that import or reference the identifier
│
├── Who imports a specific file?
│   └── find_importers(repo, file_path)
│       → all files that import from that path
│
├── All symbols defined in a file?
│   └── get_file_outline(repo, file_path)
│       → functions, classes, methods with signatures + summaries
│
└── Full source of a specific symbol?
    └── get_symbol(repo, symbol_id)
        symbol_id comes from search_symbols or get_file_outline results

Example invocations

Orient in an unfamiliar repo:

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "get_repo_outline",
  arguments: { repo: "my-project" }
)

Find authentication middleware (semantic, by description):

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "search_symbols",
  arguments: {
    repo: "my-project",
    query: "authentication middleware",
    kind: "function"
  }
)

Find all callers of validateToken:

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "find_references",
  arguments: {
    repo: "my-project",
    identifier: "validateToken"
  }
)

Find which files import UserService:

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "find_importers",
  arguments: {
    repo: "my-project",
    file_path: "src/services/UserService.ts"
  }
)

List all symbols in a file:

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "get_file_outline",
  arguments: {
    repo: "my-project",
    file_path: "src/auth/jwt.py"
  }
)

Read the full source of a specific symbol (use the symbol_id from search_symbols / get_file_outline):

CallMcpTool(
  server: "user-jcodemunch",
  toolName: "get_symbol",
  arguments: {
    repo: "my-project",
    symbol_id: "src/auth/jwt.py::verify_token",
    context_lines: 5
  }
)

Recommended workflow for serious codebase navigation

1. index_folder(path, incremental: true)   ← once per session (or skip if already done)
2. get_repo_outline(repo)                  ← understand structure
3. search_symbols(repo, query, kind?)      ← find the symbol(s) of interest
4. get_file_outline(repo, file_path)       ← explore a file's full API surface
5. find_references(repo, identifier)       ← trace all usages
6. find_importers(repo, file_path)         ← find all consumers of a module
7. get_symbol(repo, symbol_id)             ← read full source of a symbol

Fallback to grep / semantic search (Steps 1–6 below) only when:

• The codebase has not been indexed and indexing would take too long
• You need literal text matching (strings, regexes, comments)
• You're searching generated or non-standard files that the AST parser skips

When to use this skill

• Finding specific functions or classes
• Tracing function calls and dependencies
• Understanding code structure and architecture
• Finding usage examples
• Identifying code patterns
• Locating bugs or issues
• Code archaeology (understanding legacy code)
• Impact analysis before changes

Instructions

Step 1: Understand what you're looking for

Feature implementation:

• Where is feature X implemented?
• How does feature Y work?
• What files are involved in feature Z?

Bug location:

• Where is this error coming from?
• What code handles this case?
• Where is this data being modified?

API usage:

• How is this API used?
• Where is this function called?
• What are examples of using this?

Configuration:

• Where are settings defined?
• How is this configured?
• What are the config options?

Step 2: Choose search strategy

Semantic search (for conceptual questions):

Use when: You understand what you're looking for conceptually
Examples:
- "How do we handle user authentication?"
- "Where is email validation implemented?"
- "How do we connect to the database?"

Benefits:
- Finds relevant code by meaning
- Works with unfamiliar codebases
- Good for exploratory searches

Grep (for exact text/patterns):

Use when: You know exact text or patterns
Examples:
- Function names: "def authenticate"
- Class names: "class UserManager"
- Error messages: "Invalid credentials"
- Specific strings: "API_KEY"

Benefits:
- Fast and precise
- Works with regex patterns
- Good for known terms

Glob (for file discovery):

Use when: You need to find files by pattern
Examples:
- "**/*.test.js" (all test files)
- "**/config*.yaml" (config files)
- "src/**/*Controller.py" (controllers)

Benefits:
- Quickly find files by type
- Discover file structure
- Locate related files

Step 3: Search workflow

1. Start broad, then narrow:

Step 1: Semantic search "How does authentication work?"
Result: Points to auth/ directory

Step 2: Grep in auth/ for specific function
Pattern: "def verify_token"
Result: Found in auth/jwt.py

Step 3: Read the file
File: auth/jwt.py
Result: Understand implementation

2. Use directory targeting:

# Start without target (search everywhere)
Query: "Where is user login implemented?"
Target: []

# Refine with specific directory
Query: "Where is login validated?"
Target: ["backend/auth/"]

3. Combine searches:

# Find where feature is implemented
Semantic: "user registration flow"

# Find all files involved
Grep: "def register_user"

# Find test files
Glob: "**/*register*test*.py"

# Understand the implementation
Read: registration.py, test_registration.py

Step 4: Common search patterns

Find function definition:

# Python
grep -n "def function_name" --type py

# JavaScript
grep -n "function functionName" --type js
grep -n "const functionName = " --type js

# TypeScript
grep -n "function functionName" --type ts
grep -n "export const functionName" --type ts

# Go
grep -n "func functionName" --type go

# Java
grep -n "public.*functionName" --type java

Find class definition:

# Python
grep -n "class ClassName" --type py

# JavaScript/TypeScript
grep -n "class ClassName" --type js,ts

# Java
grep -n "public class ClassName" --type java

# C++
grep -n "class ClassName" --type cpp

Find class/function usage:

# Python
grep -n "ClassName(" --type py
grep -n "function_name(" --type py

# JavaScript
grep -n "new ClassName" --type js
grep -n "functionName(" --type js

Find imports/requires:

# Python
grep -n "from.*import.*ModuleName" --type py
grep -n "import.*ModuleName" --type py

# JavaScript
grep -n "import.*from.*module-name" --type js
grep -n "require.*module-name" --type js

# Go
grep -n "import.*package-name" --type go

Find configuration:

# Config files
glob "**/*config*.{json,yaml,yml,toml,ini}"

# Environment variables
grep -n "process\\.env\\." --type js
grep -n "os\\.environ" --type py

# Constants
grep -n "^[A-Z_]+\\s*=" --type py
grep -n "const [A-Z_]+" --type js

Find TODO/FIXME:

grep -n "TODO|FIXME|HACK|XXX" -i

Find error handling:

# Python
grep -n "try:|except|raise" --type py

# JavaScript
grep -n "try|catch|throw" --type js

# Go
grep -n "if err != nil" --type go

Step 5: Advanced techniques

Trace data flow:

1. Find where data is created
   Semantic: "Where is user object created?"

2. Search for variable usage
   Grep: "user\\." with context lines

3. Follow transformations
   Read: Files that modify user

4. Find where it's consumed
   Grep: "user\\." in relevant files

Find all callsites of a function:

1. Find function definition
   Grep: "def process_payment"
   Result: payments/processor.py:45

2. Find all imports of that module
   Grep: "from payments.processor import"
   Result: Multiple files

3. Find all calls to the function
   Grep: "process_payment\\("
   Result: All callsites

4. Read each callsite for context
   Read: Each file with context

Understand a feature end-to-end:

1. Find API endpoint
   Semantic: "Where is user registration endpoint?"
   Result: routes/auth.py

2. Trace to controller
   Read: routes/auth.py
   Find: Calls to AuthController.register

3. Trace to service
   Read: controllers/auth.py
   Find: Calls to UserService.create_user

4. Trace to database
   Read: services/user.py
   Find: Database operations

5. Find tests
   Glob: "**/*auth*test*.py"
   Read: Test files for examples

Find related files:

1. Start with known file
   Example: models/user.py

2. Find imports of this file
   Grep: "from models.user import"

3. Find files this imports
   Read: models/user.py
   Note: Import statements

4. Build dependency graph
   Map: All related files

Impact analysis:

Before changing function X:

1. Find all callsites
   Grep: "function_name\\("

2. Find all tests
   Grep: "test.*function_name" -i

3. Check related functionality
   Semantic: "What depends on X?"

4. Review each usage
   Read: Each file using function

5. Plan changes
   Document: Impact and required updates

Step 6: Search optimization

Use appropriate context:

# See surrounding context
grep -n "pattern" -C 5  # 5 lines before and after
grep -n "pattern" -B 3  # 3 lines before
grep -n "pattern" -A 3  # 3 lines after

Case sensitivity:

# Case insensitive
grep -n "pattern" -i

# Case sensitive (default)
grep -n "Pattern"

File type filtering:

# Specific type
grep -n "pattern" --type py

# Multiple types
grep -n "pattern" --type py,js,ts

# Exclude types
grep -n "pattern" --glob "!*.test.js"

Regex patterns:

# Any character: .
grep -n "function.*Name"

# Start of line: ^
grep -n "^class"

# End of line: $
grep -n "TODO$"

# Optional: ?
grep -n "function_name_?()"

# One or more: +
grep -n "[A-Z_]+"

# Zero or more: *
grep -n "import.*"

# Alternatives: |
grep -n "TODO|FIXME"

# Groups: ()
grep -n "(get|set)_user"

# Escape special chars: \
grep -n "function\(\)"

Best practices

1. Start with semantic search: For unfamiliar code or conceptual questions
2. Use grep for precision: When you know exact terms
3. Combine multiple searches: Build understanding incrementally
4. Read surrounding context: Don't just look at matching lines
5. Check file history: Use git blame for context
6. Document findings: Note important discoveries
7. Verify assumptions: Read actual code, don't assume
8. Use directory targeting: Narrow scope when possible
9. Follow the data: Trace data flow through the system
10. Check tests: Tests often show usage examples

Common search scenarios

Scenario 1: Understanding a bug

1. Find error message
   Grep: "exact error message"

2. Find where it's thrown
   Read: File with error

3. Find what triggers it
   Semantic: "What causes X error?"

4. Find related code
   Grep: Related function names

5. Check tests
   Glob: "**/*test*.py"
   Look: For related test cases

Scenario 2: Learning a new codebase

1. Find entry point
   Semantic: "Where does the application start?"
   Common files: main.py, index.js, app.py

2. Find main routes/endpoints
   Grep: "route|endpoint|@app\\."

3. Find data models
   Semantic: "Where are data models defined?"
   Common: models/, entities/

4. Find configuration
   Glob: "**/*config*"

5. Read README and docs
   Read: README.md, docs/

Scenario 3: Refactoring preparation

1. Find all usages
   Grep: "function_to_change"

2. Find tests
   Grep: "test.*function_to_change"

3. Find dependencies
   Semantic: "What does X depend on?"

4. Check imports
   Grep: "from.*import.*X"

5. Document scope
   List: All affected files

Scenario 4: Adding a feature

1. Find similar features
   Semantic: "How is similar feature implemented?"

2. Find where to add code
   Semantic: "Where should new feature go?"

3. Check patterns
   Read: Similar implementations

4. Find tests to emulate
   Glob: Test files for similar features

5. Check documentation
   Grep: "TODO.*new feature" -i

Tools integration

Git integration:

# Who changed this line?
git blame filename

# History of a file
git log -p filename

# Find when function was added
git log -S "function_name" --source --all

# Find commits mentioning X
git log --grep="feature name"

IDE integration:

• Use "Go to Definition" for quick navigation
• Use "Find References" for usage
• Use "Find in Files" for broad search
• Use symbol search for classes/functions

Documentation:

• Check inline comments
• Look for docstrings
• Read README files
• Check architecture docs

Troubleshooting

No results found:

• Check spelling and case sensitivity
• Try semantic search instead of grep
• Broaden search scope (remove directory target)
• Try different search terms
• Check if files are in .gitignore

Too many results:

• Add directory targeting
• Use more specific patterns
• Filter by file type
• Use exact phrases (quotes)

Wrong results:

• Be more specific in query
• Use grep instead of semantic for exact terms
• Add context to semantic queries
• Check file types

References

• Ripgrep User Guide
• Regular Expressions Tutorial
• Git Blame Guide

Examples

Example 1: Basic usage

Example 2: Advanced usage