Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rlabs-inc/codebase-curator

A set of tools to use while coding using the Claude code cli. "smartgrep" is a grep-like tool that uses a semantic index of the codebase to provide Claudes with information tailored for how they think. Claudes love it! A "codebase-curator" Claude to assist the "developer" Claude in his coding tasks, together they implement fully integrated code.
https://github.com/rlabs-inc/codebase-curator

ai ai-agents ai-assistant ai-coding ai-coding-tools ai-tools claude claude-code grep grep-like grep-search large-codebase mcp mcp-server mcp-tools

Last synced: about 1 month ago
JSON representation

A set of tools to use while coding using the Claude code cli. "smartgrep" is a grep-like tool that uses a semantic index of the codebase to provide Claudes with information tailored for how they think. Claudes love it! A "codebase-curator" Claude to assist the "developer" Claude in his coding tasks, together they implement fully integrated code.

Awesome Lists containing this project

README 

          
# 🧠 Codebase Curator



> **🎁 Give your Claude the gift of deep codebase understanding**

>

> _Because your Claude deserves a codebase expert by its side_



[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Claude Code Compatible](https://img.shields.io/badge/Claude%20Code-Compatible-blue)](https://claude.ai/code)



## 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:



```bash

# 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



```bash

# 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



```bash

# 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



```bash

# 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](https://claude.ai/code) with active subscription

- [Bun](https://bun.sh) runtime (faster than Node.js)



### Quick Start



1. **Clone and install globally**



```bash

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](./INSTALL.md)** - Detailed instructions and troubleshooting



2. **Configure Claude Code MCP**

   Add to your `claude_code_config.json`:



```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



```bash

# 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](CONTRIBUTING.md) for guidelines.



### Development



```bash

# 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](LICENSE)



## 🙏 Acknowledgments



Built with ❤️ by [RLabs Inc.](https://github.com/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](./INSTALL.md)** - Detailed setup instructions

- **[Language Support](./docs/LANGUAGE_SUPPORT.md)** - All 10 supported languages

- **[Smart Grep Guide](./docs/SMART_GREP_GUIDE.md)** - Advanced search techniques

- **[Architecture Overview](./docs/ARCHITECTURE.md)** - How it all works

- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions

- **[Release Notes v4.0](./docs/RELEASE_NOTES_v4.md)** - 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