Smart Grep is not just another search tool - it understands code structure and provides semantic insights about your codebase.
Traditional grep searches text. Smart Grep understands:
- Code Structure: Functions, classes, variables, imports
- Usage Patterns: How many times something is used
- Cross-References: Where things are called from
- Context: Surrounding code that matters
# After installing Codebase Curator
cd codebase-curator
bun link
# Now available globally
smartgrep --help
smartgrep "user"
Returns all user-related code organized by type:
- Functions with "user"
- Classes with "user"
- Variables with "user"
- Comments mentioning "user"
smartgrep "login|auth|signin"
Finds any of these terms.
smartgrep "async&function"
Finds async functions only.
smartgrep "!test" --type function
Find all functions except tests.
smartgrep "/user.*Service/" --regex
Full regex pattern matching.
smartgrep "UserService" --exact
Case-sensitive exact matches only.
# Single type
smartgrep "database" --type function
# Multiple types
smartgrep "api" --type function,class
# Available types:
# function, class, variable, interface,
# type, import, comment, string
# Search only in service files
smartgrep "error" --file "*.service.ts"
# Search in specific directory
smartgrep "config" --file "src/core/*"
# Sort by most used
smartgrep "function" --sort usage
# Find unused code
smartgrep "function" --sort usage | grep "(0 uses)"
Find where something is used:
smartgrep refs "PaymentService"
Shows every location that references PaymentService:
📎 Cross-references for "PaymentService":
├── Used in handlePayment() → controllers/checkout.ts:45
├── Imported by OrderService → services/order.ts:3
├── Instantiated in main() → index.ts:23
└── Tested in payment.test.ts → tests/payment.test.ts:12
Analyze the impact of your uncommitted changes:
# Full impact analysis
smartgrep changes
Shows:
📊 Changes Impact Analysis
📍 Branch: main
📝 Status: 2 staged, 5 unstaged
📄 Files Changed:
├── src/services/PaymentService.ts
│ └── Modified: processPayment, validateCard (2 symbols)
└── src/controllers/checkout.ts
└── Modified: handleCheckout (1 symbol)
🔗 Impact: 3 files will be affected
├── tests/payment.test.ts:45 - References processPayment
├── src/api/routes.ts:23 - Imports PaymentService
└── src/services/order.ts:67 - Calls handleCheckout
⚠️ Risk Level: Medium - Changes affect core payment flow
Quick risk assessment:
smartgrep changes --compact
# Returns: ⚠️ Medium Risk: 7 files changed → 15 references across 8 files
smartgrep "authenticate"
Shows full context, signatures, and usage counts.
smartgrep "authenticate" --compact
One line per result for scanning.
smartgrep "authenticate" --no-context
Just the matches without surrounding code.
smartgrep "user" --max 10
Limit number of results.
Smart Grep understands common programming concepts:
# List all available groups
smartgrep group list
# Authentication patterns
smartgrep group auth
# Error handling
smartgrep group error
# Database operations
smartgrep group database
# API endpoints
smartgrep group api
# State management
smartgrep group state
Create project-specific semantic patterns:
# Add a custom group
smartgrep group add payments charge,bill,invoice,transaction,payment
smartgrep group add frontend component,render,props,state,ui
# Search with your custom groups
smartgrep group payments
smartgrep group payments --type function
smartgrep group frontend --sort usage
# Remove a custom group
smartgrep group remove payments
Custom groups are saved in .curatorconfig.json
:
{
"customGroups": {
"payments": ["charge", "bill", "invoice", "transaction", "payment"],
"frontend": {
"name": "frontend",
"description": "Frontend UI patterns",
"emoji": "🎨",
"terms": ["component", "render", "props", "state", "ui"]
}
}
}
# Find main entry points
smartgrep "main|init|start" --type function
# Understand the architecture
smartgrep "service|controller|model" --type class
# Find configuration
smartgrep "config|settings|env"
# Find similar features
smartgrep "user|profile" --type class,function
# Understand the patterns
smartgrep refs "UserService"
# Find where to add code
smartgrep "router|route|endpoint"
# Find error handling
smartgrep "catch|error|exception"
# Trace function calls
smartgrep refs "problematicFunction"
# Find logging
smartgrep "console|log|debug"
# Find duplicated patterns
smartgrep "getData" --type function
# Find unused exports
smartgrep "export" --sort usage | grep "(0 uses)"
# Find long functions
smartgrep "function" --sort length
# Before committing, check impact
smartgrep changes
# Quick check
smartgrep changes --compact
# ✅ Low Risk: 2 files changed → 3 references
# ⚠️ Medium Risk: Core services affected
# 🚨 High Risk: Breaking changes detected
# If risky, find all affected tests
smartgrep refs "modifiedFunction" --file "*test*"
- Use specific types:
--type function
is faster than searching everything - Use file patterns:
--file "*.service.*"
narrows the search - Combine filters: Multiple filters work together for precision
- Use concept groups: Predefined groups are optimized
When Curator Claude analyzes your codebase, it uses smart grep extensively:
// In prompts
"bun run smartgrep service"
"bun run smartgrep error --type function"
"bun run smartgrep refs 'MainComponent'"
This is how it quickly understands your patterns and architecture.
Run in your project root or build the index:
cd your-project
smartgrep --index
The index auto-updates, but you can force rebuild:
smartgrep --index
Use filters to narrow down:
smartgrep "user" --type function --file "src/*" --max 20
Add support for new languages by creating extractors in:
src/semantic/extractors/
Define project-specific concepts in:
.curatorconfig.json
Adjust indexing settings:
{
"semantic": {
"maxFileSize": "500KB",
"excludePatterns": ["*.min.js"],
"incrementalIndex": true
}
}
- Faster Understanding: See code organization instantly
- Better Navigation: Jump to the right place immediately
- Smarter Refactoring: Know what depends on what
- Effective Debugging: Trace issues through the codebase
- Code Quality: Find unused code and duplications
Smart Grep is your semantic lens into the codebase - use it to see not just text, but meaning.