Codebase Curator

🎁 Give your Claude the gift of deep codebase understanding

Because your Claude deserves a codebase expert by its side

License: MIT Claude Code Compatible

What is Codebase Curator?

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.

The Problem

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

The Solution: Two-Claude Architecture

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

✨ Key Features

🤖 Two-Claude Architecture

• 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 - Semantic Search That Understands Code

🚀 NEW: Compact Mode for Claudes (90% Less Context Usage!)

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!

Core Features

# 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

🌐 Language Support - Now 14 Languages + Frameworks!

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

🎯 Live Monitoring Dashboard

# 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

🧠 Persistent Understanding

• First question: Curator Claude explores and learns your codebase
• Every question after: Builds on that understanding
• Result: Faster, more accurate, context-aware responses

🚀 Real Examples

# 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

📦 Installation

Prerequisites

• Claude Code with active subscription
• Bun runtime (faster than Node.js)

Quick Start

1. 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 search
• curator-monitor - Live monitoring
• codebase-curator - Interactive CLI

📚 Full Installation Guide - Detailed instructions and troubleshooting

2. 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"]
    }
  }
}

3. Restart Claude Code The Codebase Curator tools will appear in Claude's tool panel.

🎯 Usage

In Claude Code

1. Set your project

Use the set_project_path tool:
Path: /path/to/your/project

2. Get an overview (do this first!)

Use the get_codebase_overview tool

3. 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"

Smart Grep CLI - Semantic Search Made Simple

# 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

🏗️ Architecture

Monorepo Structure

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

Two-Claude System

• Coding Claude: You, working in Claude Code
• Curator Claude: Your dedicated codebase expert
• Communication: Via MCP (Model Context Protocol)

Smart Components

• 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

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development

# 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

MCP Tools Available

• get_codebase_overview - Deep analysis of your codebase
• ask_curator - Ask questions about the code
• add_new_feature - Get guidance for new features
• implement_change - Get help with specific changes
• list_project_special_tools - Discover AI-optimized tools
• remind_about_smartgrep - Get smart-grep usage examples

📄 License

MIT - see LICENSE

🙏 Acknowledgments

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! 🚀

📚 Documentation

• 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

🎆 What's New

v4.0 - Git Impact Analysis & Custom Groups

• Git Changes Analysis: smartgrep changes analyzes 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

v3.0 - Smart Grep Revolution

• Concept Groups: smartgrep group auth searches 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

v2.3 - Incremental Indexing

• 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