Claude-Code-Workflow/.claude/skills/context-search/reference.md

Context Search Command Reference

Complete reference for all context search tools and commands.

Tool Overview

codebase-retrieval (Semantic Discovery)

Purpose: Intelligent file discovery based on task/feature context using Gemini CLI

Command Syntax:

~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [description]"

Parameters:

• --all-files: Enable all-files mode for semantic discovery
• -p "prompt": Provide task/feature description

Use When:

• Need to find files related to a concept or feature
• Don't know exact file names
• Want AI-powered file discovery
• Exploring unfamiliar codebase

Best Practices:

• Be specific in description
• Include technology stack terms (e.g., "JWT authentication", "React components")
• Mention file types if relevant (e.g., "TypeScript interfaces")

---

rg (ripgrep)

Purpose: Fast content search with regex support

Command Syntax:

rg [OPTIONS] PATTERN [PATH...]

Common Options:

Option	Description	Example
-i, --ignore-case	Case-insensitive search	rg -i "pattern"
-n, --line-number	Show line numbers	rg -n "pattern"
-A NUM	Show NUM lines after match	rg -A 3 "pattern"
-B NUM	Show NUM lines before match	rg -B 3 "pattern"
-C NUM	Show NUM lines before and after	rg -C 3 "pattern"
--type TYPE	Search only TYPE files	rg --type ts "pattern"
--glob PATTERN	Include/exclude files by glob	rg --glob '!*.test.js'
-F, --fixed-strings	Treat pattern as literal string	rg -F "exact.match"
-l, --files-with-matches	Show only filenames	rg -l "pattern"
-c, --count	Show count of matches per file	rg -c "pattern"
-w, --word-regexp	Match whole words only	rg -w "pattern"
--no-ignore	Don't respect .gitignore	rg --no-ignore "pattern"

File Type Filters:

rg --type-list           # List all available types

# Common types
rg --type js "pattern"   # JavaScript
rg --type ts "pattern"   # TypeScript
rg --type py "pattern"   # Python
rg --type rust "pattern" # Rust
rg --type go "pattern"   # Go
rg --type java "pattern" # Java
rg --type cpp "pattern"  # C++
rg --type html "pattern" # HTML
rg --type css "pattern"  # CSS
rg --type json "pattern" # JSON
rg --type yaml "pattern" # YAML

Glob Patterns:

# Include patterns
rg "pattern" --glob '*.ts'        # Only TypeScript files
rg "pattern" --glob 'src/**/*.js' # JS files in src/

# Exclude patterns
rg "pattern" --glob '!*.test.js'    # Exclude test files
rg "pattern" --glob '!node_modules' # Exclude node_modules
rg "pattern" --glob '!dist'         # Exclude dist directory

# Multiple globs
rg "pattern" --glob '*.ts' --glob '*.tsx' --glob '!*.test.*'

Performance Tips:

• Use --type instead of --glob when possible (faster)
• Use -F for literal strings (no regex overhead)
• Exclude large directories with --glob '!node_modules'
• Limit search to specific paths: rg "pattern" src/

---

find

Purpose: Locate files and directories by name patterns

Command Syntax:

find [PATH...] [OPTIONS] [EXPRESSION]

Common Options:

Option	Description	Example
-name PATTERN	Match filename pattern	find . -name "*.ts"
-iname PATTERN	Case-insensitive name match	find . -iname "*.TXT"
-type TYPE	Match file type (f=file, d=dir)	find . -type f
-path PATTERN	Match full path pattern	find . -path "*/src/*"
-prune	Don't descend into directory	find . -path "*/node_modules" -prune
-maxdepth N	Descend at most N levels	find . -maxdepth 2
-mindepth N	Start at least N levels deep	find . -mindepth 1
-exec CMD {} \;	Execute command on results	find . -name "*.js" -exec wc -l {} \;

Common Patterns:

# Find files by extension
find . -name "*.ts" -type f
find . -name "*.js" -o -name "*.jsx"

# Find files excluding directories
find . -path "*/node_modules" -prune -o -name "*.js" -print
find . -path "*/dist" -prune -o -path "*/.git" -prune -o -type f -print

# Find files and execute command
find . -name "*.test.js" -exec grep -l "describe" {} \;
find . -name "*.ts" -type f -exec wc -l {} \; | sort -n

# Find by depth
find . -maxdepth 2 -name "*.json"
find . -mindepth 2 -maxdepth 3 -name "package.json"

# Find directories
find . -type d -name "*test*"

# Find empty files
find . -type f -empty

# Find files modified recently
find . -name "*.js" -mtime -7  # Modified in last 7 days

---

grep

Purpose: Built-in pattern matching (fallback when rg unavailable)

Command Syntax:

grep [OPTIONS] PATTERN [FILE...]

Common Options:

Option	Description	Example
-r, --recursive	Search recursively	grep -r "pattern" .
-i, --ignore-case	Case-insensitive	grep -i "pattern" file
-n, --line-number	Show line numbers	grep -n "pattern" file
-A NUM	Show NUM lines after	grep -A 3 "pattern" file
-B NUM	Show NUM lines before	grep -B 3 "pattern" file
-C NUM	Show NUM lines context	grep -C 3 "pattern" file
-l, --files-with-matches	Show only filenames	grep -l "pattern" *.js
-c, --count	Count matches per file	grep -c "pattern" *.js
-v, --invert-match	Show non-matching lines	grep -v "pattern" file
-w, --word-regexp	Match whole words	grep -w "word" file
-E, --extended-regexp	Extended regex	`grep -E "pat1
--include=PATTERN	Include files matching	grep -r "pattern" --include="*.js"
--exclude=PATTERN	Exclude files matching	grep -r "pattern" --exclude="*.test.js"
--exclude-dir=PATTERN	Exclude directories	grep -r "pattern" --exclude-dir="node_modules"

Common Patterns:

# Recursive search
grep -r "pattern" .
grep -r "pattern" --include="*.ts" --exclude-dir="node_modules" .

# Case-insensitive with line numbers
grep -i -n "pattern" file.txt

# Show context
grep -A 3 -B 3 "pattern" file.txt
grep -C 5 "pattern" file.txt

# Multiple patterns
grep -E "pattern1|pattern2" file.txt
grep "pattern1" file.txt | grep "pattern2"

# Invert match (exclude lines)
grep -v "exclude" file.txt

# Count matches
grep -c "pattern" *.js

# Find files containing pattern
grep -l "pattern" *.js
grep -r -l "pattern" --include="*.ts" .

Note: Prefer rg over grep for better performance and features.

---

get_modules_by_depth.sh

Purpose: Program architecture analysis and structural discovery

Command Syntax:

~/.claude/scripts/get_modules_by_depth.sh

No Options: Script runs automatically and analyzes current directory structure

Use When:

• Starting a new planning task (MANDATORY)
• Need to understand program architecture
• Exploring project structure
• Before making structural changes

Output: Hierarchical view of program modules and their relationships

Best Practices:

• Run before any planning or architecture work
• Run from project root directory
• Use output to inform file organization decisions
• Reference output when discussing architecture

---

MCP Code Index Tools

mcp__code-index__search_code_advanced

Purpose: Advanced code pattern search with fuzzy matching

Parameters:

{
  pattern: string,              // Search pattern (regex or literal)
  case_sensitive?: boolean,     // Default: true
  context_lines?: number,       // Default: 0
  file_pattern?: string,        // Glob pattern (e.g., "*.ts")
  fuzzy?: boolean,              // Default: false
  max_line_length?: number,     // Default: none
  regex?: boolean               // Default: null (auto-detect)
}

Examples:

# Basic search
mcp__code-index__search_code_advanced(pattern="function.*auth")

# With file filter
mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")

# Case-insensitive with context
mcp__code-index__search_code_advanced(pattern="error", case_sensitive=false, context_lines=3)

# Fuzzy search
mcp__code-index__search_code_advanced(pattern="auhtenticate", fuzzy=true)

---

mcp__code-index__find_files

Purpose: Find files by glob pattern using pre-built index

Parameters:

{
  pattern: string  // Glob pattern (e.g., "*.ts", "*auth*")
}

Pattern Types:

• Full path matching: src/**/*.ts
• Filename only: README.md (finds all README files)
• Wildcard: *auth* (files containing "auth")

Examples:

# Find all Markdown files
mcp__code-index__find_files(pattern="*.md")

# Find files with wildcard
mcp__code-index__find_files(pattern="*auth*")

# Find test files
mcp__code-index__find_files(pattern="*.test.ts")

# Find specific file
mcp__code-index__find_files(pattern="package.json")

Note: Use wildcard patterns for better results than exact matches.

---

mcp__code-index__refresh_index

Purpose: Manually refresh project file index

Parameters: None

Use When:

• After major git operations (pull, merge, checkout)
• File watcher is disabled or unavailable
• Index seems outdated
• Large-scale file operations completed

Example:

mcp__code-index__refresh_index()

---

mcp__code-index__get_file_summary

Purpose: Get structural summary of a file

Parameters:

{
  file_path: string  // Path to file
}

Returns:

• Line count
• Function/class definitions
• Import statements
• Basic complexity metrics

Example:

mcp__code-index__get_file_summary(file_path="src/auth/index.ts")

---

Performance Comparison

Speed Rankings (Fastest to Slowest)

1. rg (ripgrep) - Fastest for content search
2. find - Fast for file location
3. MCP Code Index - Fast for indexed searches
4. grep - Slower than rg
5. codebase-retrieval - Slower (AI-powered)

Recommended Tool by Task

Task	Fastest Tool	Alternative
Content search	rg	grep
File location	find	MCP find_files
Pattern search	rg	MCP search_code_advanced
Semantic discovery	codebase-retrieval	-
Architecture analysis	get_modules_by_depth.sh	-

---

Optimization Strategies

General Tips

1. Use type filters - Always specify file types when possible
2. Exclude directories - Skip node_modules, dist, .git
3. Literal search - Use -F flag when pattern has no regex
4. Limit scope - Search specific directories instead of entire project
5. Use indexes - MCP Code Index is fast for indexed operations

Pattern Optimization

# ❌ Slow: Complex regex
rg ".*complex.*nested.*pattern.*"

# ✅ Fast: Simple patterns
rg "complex" | rg "nested" | rg "pattern"

# ❌ Slow: No type filter
rg "pattern"

# ✅ Fast: With type filter
rg "pattern" --type ts

# ❌ Slow: Searches everything
rg "pattern" .

# ✅ Fast: Limited scope
rg "pattern" src/

Exclusion Patterns

# Standard exclusions for most projects
rg "pattern" \
  --glob '!node_modules' \
  --glob '!dist' \
  --glob '!build' \
  --glob '!.git' \
  --glob '!coverage' \
  --glob '!*.min.js'

# With find
find . \
  -path "*/node_modules" -prune -o \
  -path "*/dist" -prune -o \
  -path "*/.git" -prune -o \
  -name "*.ts" -print

---

Environment-Specific Notes

Git Bash on Windows

• All commands work in Git Bash environment
• Use forward slashes (/) in paths
• Use POSIX-style paths (/c/Users instead of C:\Users)
• ❌ No Windows commands: findstr, dir, where, type
• ✅ Use Bash equivalents: grep, find, which, cat

Path Handling

# ✅ Correct (Bash)
find . -name "*.ts"
rg "pattern" src/

# ❌ Wrong (Windows)
dir /s /b *.ts
findstr /s "pattern" src\

---

Troubleshooting

Command Not Found

# Check if rg is installed
which rg

# Fallback to grep if rg unavailable
if ! command -v rg &> /dev/null; then
  grep -r "pattern" .
else
  rg "pattern"
fi

Too Many Results

# Add more specific patterns
rg "very.specific.pattern" --type ts

# Limit to directory
rg "pattern" src/auth/

# Show only filenames
rg "pattern" -l

# Count matches
rg "pattern" -c

Too Slow

# Use literal search
rg -F "literal" --type ts

# Exclude large directories
rg "pattern" --glob '!node_modules' --glob '!dist'

# Limit depth
find . -maxdepth 3 -name "*.ts"

# Use type filters
rg "pattern" --type ts

No Matches Found

# Try case-insensitive
rg -i "pattern"

# Try fuzzy search (MCP)
mcp__code-index__search_code_advanced(pattern="patern", fuzzy=true)

# Check if file type is correct
rg "pattern" --type-list

# Try without filters
rg "pattern" .

---

Advanced Usage

Combining Tools

# Use find to get files, rg to search within
find . -name "*.ts" -type f | xargs rg "pattern"

# Use rg to find files, then process
rg -l "pattern" --type ts | xargs wc -l

# Semantic discovery → content search
FILES=$(~/.claude/scripts/gemini-wrapper --all-files -p "List files for: auth")
echo "$FILES" | xargs rg "jwt"

Piping Results

# Chain searches
rg "pattern1" --type ts | rg "pattern2"

# Count results
rg "pattern" -l | wc -l

# Sort by frequency
rg "pattern" -c | sort -t: -k2 -n

# Get unique matches
rg "pattern" -o | sort | uniq -c | sort -n

Custom Scripts

# Create custom search function
search_feature() {
  local feature=$1
  echo "Searching for: $feature"

  # Semantic discovery
  ~/.claude/scripts/gemini-wrapper --all-files -p "List files for: $feature"

  # Content search
  rg "$feature" --type ts -C 2
}

# Use it
search_feature "authentication"

---

Quick Reference Card

Most Common Commands

# Semantic file discovery
~/.claude/scripts/gemini-wrapper --all-files -p "List files for: [task]"

# Architecture analysis
~/.claude/scripts/get_modules_by_depth.sh

# Content search
rg "pattern" --type ts

# File search
find . -name "*.ts" -type f

# MCP search
mcp__code-index__search_code_advanced(pattern="pattern", file_pattern="*.ts")

# MCP find
mcp__code-index__find_files(pattern="*pattern*")

Common Options

# Case-insensitive
rg -i "pattern"

# Show context
rg -C 3 "pattern"

# Exclude directory
rg "pattern" --glob '!node_modules'

# Literal search
rg -F "exact.match"

# Type filter
rg "pattern" --type ts

---

See Also

• SKILL.md - Core decision framework
• examples.md - Practical usage examples
• ripgrep documentation: https://github.com/BurntSushi/ripgrep
• find man page: man find
• grep man page: man grep