🎁 Give your Claude the gift of deep codebase understanding
Because your Claude deserves a codebase expert by its side
License: MIT Claude Code Compatible
Codebase Curator transforms how Claude understands your code. Instead of treating each question as isolated, it gives Claude a persistent, intelligent companion that deeply understands your entire codebase.
When you ask Claude about your codebase, it starts from scratch every time:
- 🔄 Repetitive exploration of the same files
- ⏰ Slow responses as it re-discovers your architecture
- 🎯 Inconsistent understanding between questions
- 😕 Generic suggestions that don't fit your patterns
Codebase Curator spawns a dedicated "Curator Claude" that becomes an expert on YOUR specific codebase:
You (Coding Claude) → "How do I add authentication?"
↓
Codebase Curator → Spawns Curator Claude
↓
Curator Claude → Deeply analyzes your codebase
↓
You get → Specific guidance that fits YOUR patterns
- Curator Claude: A dedicated AI that becomes an expert on YOUR codebase
- Persistent Sessions: Remembers context between questions
- Instant Follow-ups: First question takes 2 minutes, rest are instant
Smart Grep now defaults to a compact summary mode that's optimized for AI assistants:
# Default: Compact summary (perfect for Claudes) smartgrep "authService" ══════════════════════════════════════════════════════════════════════ 🔍 SMARTGREP: "authService" (17 results in 4 files) 📍 DEFINITION: auth/service.ts:42 (CLASS) export class AuthService { constructor(db: Database, cache: Cache) 🔥 TOP USAGE: • api/routes.ts: - Line 15: authService.authenticate(username, password) - Line 23: authService.validateToken(token) • middleware/auth.ts:12 - if (!authService.isValid(token)) ⚡ BREAKING CHANGES (if you modify this): • LoginController.handleLogin() - calls authenticate() • AuthMiddleware.verify() - calls validateToken() 💡 PATTERNS DETECTED: • Always async/await calls • Throws: AuthenticationError, TokenExpiredError 🎯 NEXT: smartgrep refs "authService" | smartgrep "authenticate" ══════════════════════════════════════════════════════════════════════ # Need full details? Use --full flag smartgrep "authService" --full # Complete analysis with all matches
Why This Matters for Claudes:
- Before: Each search consumed 2000-3000 tokens
- Now: Only 200-300 tokens per search
- Result: 10x more searches before hitting context limits!
# Don't just search - understand! smartgrep "handleAuth" # Shows where it's used + usage count smartgrep refs "apiClient" # Full impact analysis - see all references smartgrep group auth # Search ALL auth patterns at once smartgrep changes # Analyze your uncommitted changes impact smartgrep changes --compact # Quick risk assessment before committing smartgrep "func NewAuth" # Go functions smartgrep "impl Auth" # Rust implementations smartgrep "protocol Auth" # Swift protocols smartgrep "function deploy" # Shell scripts # Returns organized results with usage counts: # → Functions: authenticate() (12 uses), validateUser() (5 uses) # → Classes: AuthService, AuthMiddleware # → Config: JWT_SECRET, AUTH_URL, oauth settings # → Cross-references: Shows actual calling code with file:line locations # Advanced patterns smartgrep "error&handler" # AND search smartgrep "login|signin|auth" # OR search smartgrep "!test" --type function # Exclude tests # Custom concept groups for your project smartgrep group add payments charge,bill,invoice,transaction smartgrep group payments --type function # Search your custom group
Programming Languages:
- TypeScript/JavaScript - Full AST parsing, JSX/TSX, ES6+, decorators
- Python - Classes, decorators, async, type hints, docstrings, dataclasses
- Go - Interfaces, goroutines, channels, embedded types, generics
- Rust - Traits, macros, lifetimes, async, unsafe blocks, derive
- Swift - Protocols, SwiftUI, extensions, property wrappers, actors
- Shell - Functions, aliases, exports, heredocs, arrays
Framework Files (NEW!):
- Svelte (.svelte) - Runes ($state, $derived), stores, lifecycle hooks, directives
- Vue (.vue) - Composition API, SFC, directives (v-if, v-for), defineProps
- Astro (.astro) - Props interface, client directives, Astro.props
- MDX (.mdx) - Markdown with JSX components, imports, exports
Configuration Files:
- JSON - package.json, tsconfig.json, hierarchical parsing
- YAML - CI/CD pipelines, Docker Compose, Kubernetes manifests
- TOML - Cargo.toml, pyproject.toml, structured configs
- Environment - .env files with secure value masking
# Watch your codebase evolve in real-time bun run monitor watch --overview # See: # → Live code distribution by type # → File changes as they happen # → Most complex files by declaration count # → Automatic reindexing on changes
- First question: Curator Claude explores and learns your codebase
- Every question after: Builds on that understanding
- Result: Faster, more accurate, context-aware responses
# Overview - The foundation (takes ~2 minutes) "Give me an overview of this codebase" → Curator explores everything, understands patterns # Follow-up questions are instant and accurate "How does authentication work?" → Immediate response with YOUR specific implementation "Where should I add a payment feature?" → Knows your patterns, suggests the right location
- Claude Code with active subscription
- Bun runtime (faster than Node.js)
- Clone and install globally
git clone https://github.com/RLabs-Inc/codebase-curator.git cd codebase-curator bun install bun link # Makes commands available globally
Now you can use these commands from anywhere:
smartgrep- Semantic code searchcurator-monitor- Live monitoringcodebase-curator- Interactive CLI
📚 Full Installation Guide - Detailed instructions and troubleshooting
- Configure Claude Code MCP
Add to your
claude_code_config.json:
{
"mcpServers": {
"codebase-curator": {
"command": "bun",
"args": ["run", "/path/to/codebase-curator/src/mcp-servers/codebase-curator/server.ts"]
}
}
}- Restart Claude Code The Codebase Curator tools will appear in Claude's tool panel.
- Set your project
Use the set_project_path tool:
Path: /path/to/your/project
- Get an overview (do this first!)
Use the get_codebase_overview tool
- Ask questions
Use ask_curator: "How does the payment system work?"
Use add_new_feature: "Add user notifications"
Use implement_change: "Fix the login timeout bug"
# After installation with bun link, use from anywhere: # Concept groups - search semantic patterns smartgrep group auth # ALL auth patterns (login, jwt, token...) smartgrep group error # ALL error patterns (exception, fail...) smartgrep group api # ALL API patterns (endpoint, route...) smartgrep group list # See all 20+ concept groups # NEW: Analyze your changes before committing! smartgrep changes # Full impact analysis of uncommitted changes smartgrep changes --compact # Quick risk assessment (one line) # Advanced search patterns smartgrep "user|auth" # OR search smartgrep "async&function" # AND search smartgrep "!test" --type function # Exclude tests smartgrep refs "PaymentService" # Find all usages # Custom groups for your project smartgrep group add payments charge,bill,invoice,transaction smartgrep group payments # Use your custom group # Type filters for precision smartgrep "auth" --type function # Only functions smartgrep "error" --type string # Only string literals smartgrep group api --type class # Only API classes # Sort and format options smartgrep group service --sort usage # Most used first smartgrep "user" --compact # One line per result smartgrep "api" --json # Machine-readable output
src/
├── packages/ # Distributable packages
│ ├── semantic-core/ # Core indexing engine
│ ├── smartgrep/ # Semantic search CLI
│ └── codebase-curator/ # Full suite
├── services/ # Shared business logic
├── tools/ # CLI interfaces
├── mcp-servers/ # AI interfaces
└── shared/ # Common utilities
- Coding Claude: You, working in Claude Code
- Curator Claude: Your dedicated codebase expert
- Communication: Via MCP (Model Context Protocol)
- Session Persistence: Maintains context between questions with --resume
- Dynamic Timeouts: Adapts to different operations (Task: 10min, Bash: 5min)
- Semantic Indexing: Understands code structure with 20+ concept groups
- Incremental Indexing: Only reprocesses changed files with debouncing
- Live Monitoring: Real-time dashboard shows code evolution as you work
- Cross-References: Shows not just where code is defined, but who uses it
- Streaming Architecture: Handles massive codebases efficiently
- Package Distribution: Each tool can be installed independently
We welcome contributions! See CONTRIBUTING.md for guidelines.
# Install workspace dependencies bun install # Run tests bun test # Run MCP server locally bun run mcp # Run CLI tools bun run start # Curator CLI bun run smartgrep [query] # Smart grep bun run monitor watch --overview # Live monitoring # Build semantic index bun run smartgrep --index # Analyze your changes bun run smartgrep changes # Full impact analysis bun run smartgrep changes -c # Quick risk check # Work with packages cd src/packages/smartgrep bun run build # Build for distribution bun run build:binary # Create standalone binary
get_codebase_overview- Deep analysis of your codebaseask_curator- Ask questions about the codeadd_new_feature- Get guidance for new featuresimplement_change- Get help with specific changeslist_project_special_tools- Discover AI-optimized toolsremind_about_smartgrep- Get smart-grep usage examples
MIT - see LICENSE
Built with ❤️ by RLabs Inc. and Claude
Special thanks to the Claude Code team for making this integration possible.
Remember: Your Claude works hard to help you code. Give it the superpower it deserves! 🚀
- Installation Guide - Detailed setup instructions
- Language Support - All 10 supported languages
- Smart Grep Guide - Advanced search techniques
- Architecture Overview - How it all works
- Troubleshooting - Common issues and solutions
- Release Notes v4.0 - Latest updates
- Git Changes Analysis:
smartgrep changesanalyzes uncommitted changes impact - Custom Concept Groups: Create project-specific semantic patterns
- Performance: 37x faster than standalone tools (1s vs 37.5s)
- Risk Assessment: One-line safety check before committing
- 10 Language Support: Added Swift and Shell script support
- Concept Groups:
smartgrep group authsearches semantic patterns - Advanced Search: AND/OR/NOT patterns, regex support
- Type Filters: Search only functions, classes, variables, etc.
- Live Monitoring: Real-time codebase overview dashboard
- MCP Discovery: Tools help Claudes discover smart-grep features
- Hash Tree: Bun.hash() for instant file change detection
- Smart Debouncing: Handles duplicate save events gracefully
- Silent Mode: Clean output for live monitoring
- Unique File Tracking: Shows real changes, not event counts