{"id":28435579,"url":"https://github.com/rlabs-inc/codebase-curator","last_synced_at":"2026-05-09T00:02:10.039Z","repository":{"id":295856573,"uuid":"991419591","full_name":"RLabs-Inc/codebase-curator","owner":"RLabs-Inc","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-13T16:15:02.000Z","size":7781,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T13:45:20.426Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RLabs-Inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-27T15:40:32.000Z","updated_at":"2025-06-21T23:36:24.000Z","dependencies_parsed_at":"2025-06-13T12:34:30.032Z","dependency_job_id":"fb5fb2da-734b-4465-82e1-aa1fd7ce099e","html_url":"https://github.com/RLabs-Inc/codebase-curator","commit_stats":null,"previous_names":["rlabs-inc/codebase-curator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RLabs-Inc/codebase-curator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLabs-Inc%2Fcodebase-curator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLabs-Inc%2Fcodebase-curator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLabs-Inc%2Fcodebase-curator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLabs-Inc%2Fcodebase-curator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RLabs-Inc","download_url":"https://codeload.github.com/RLabs-Inc/codebase-curator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLabs-Inc%2Fcodebase-curator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32802533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-06-05T20:40:19.499Z","updated_at":"2026-05-09T00:02:10.032Z","avatar_url":"https://github.com/RLabs-Inc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# šŸ§  Codebase Curator\n\n\u003e **šŸŽ Give your Claude the gift of deep codebase understanding**\n\u003e\n\u003e _Because your Claude deserves a codebase expert by its side_\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code Compatible](https://img.shields.io/badge/Claude%20Code-Compatible-blue)](https://claude.ai/code)\n\n## What is Codebase Curator?\n\nCodebase 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.\n\n### The Problem\n\nWhen you ask Claude about your codebase, it starts from scratch every time:\n\n- šŸ”„ Repetitive exploration of the same files\n- ā° Slow responses as it re-discovers your architecture\n- šŸŽÆ Inconsistent understanding between questions\n- šŸ˜• Generic suggestions that don't fit your patterns\n\n### The Solution: Two-Claude Architecture\n\nCodebase Curator spawns a dedicated \"Curator Claude\" that becomes an expert on YOUR specific codebase:\n\n```\nYou (Coding Claude) ā†’ \"How do I add authentication?\"\n ā†“\nCodebase Curator ā†’ Spawns Curator Claude\n ā†“\nCurator Claude ā†’ Deeply analyzes your codebase\n ā†“\nYou get ā†’ Specific guidance that fits YOUR patterns\n```\n\n## āœØ Key Features\n\n### šŸ¤– Two-Claude Architecture\n- **Curator Claude**: A dedicated AI that becomes an expert on YOUR codebase\n- **Persistent Sessions**: Remembers context between questions\n- **Instant Follow-ups**: First question takes 2 minutes, rest are instant\n\n### šŸ” Smart Grep - Semantic Search That Understands Code\n\n#### šŸš€ NEW: Compact Mode for Claudes (90% Less Context Usage!)\n\nSmart Grep now defaults to a **compact summary mode** that's optimized for AI assistants:\n\n```bash\n# Default: Compact summary (perfect for Claudes)\nsmartgrep \"authService\"\n\nā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•\nšŸ” SMARTGREP: \"authService\" (17 results in 4 files)\n\nšŸ“ DEFINITION: auth/service.ts:42 (CLASS)\n export class AuthService {\n constructor(db: Database, cache: Cache)\n\nšŸ”„ TOP USAGE:\n ā€¢ api/routes.ts:\n - Line 15: authService.authenticate(username, password)\n - Line 23: authService.validateToken(token)\n ā€¢ middleware/auth.ts:12 - if (!authService.isValid(token))\n\nāš” BREAKING CHANGES (if you modify this):\n ā€¢ LoginController.handleLogin() - calls authenticate()\n ā€¢ AuthMiddleware.verify() - calls validateToken()\n\nšŸ’” PATTERNS DETECTED:\n ā€¢ Always async/await calls\n ā€¢ Throws: AuthenticationError, TokenExpiredError\n\nšŸŽÆ NEXT: smartgrep refs \"authService\" | smartgrep \"authenticate\"\nā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•\n\n# Need full details? Use --full flag\nsmartgrep \"authService\" --full # Complete analysis with all matches\n```\n\n**Why This Matters for Claudes:**\n- **Before**: Each search consumed 2000-3000 tokens\n- **Now**: Only 200-300 tokens per search\n- **Result**: 10x more searches before hitting context limits!\n\n#### Core Features\n\n```bash\n# Don't just search - understand!\nsmartgrep \"handleAuth\" # Shows where it's used + usage count\nsmartgrep refs \"apiClient\" # Full impact analysis - see all references\nsmartgrep group auth # Search ALL auth patterns at once\nsmartgrep changes # Analyze your uncommitted changes impact\nsmartgrep changes --compact # Quick risk assessment before committing\nsmartgrep \"func NewAuth\" # Go functions\nsmartgrep \"impl Auth\" # Rust implementations\nsmartgrep \"protocol Auth\" # Swift protocols\nsmartgrep \"function deploy\" # Shell scripts\n\n# Returns organized results with usage counts:\n# ā†’ Functions: authenticate() (12 uses), validateUser() (5 uses)\n# ā†’ Classes: AuthService, AuthMiddleware \n# ā†’ Config: JWT_SECRET, AUTH_URL, oauth settings\n# ā†’ Cross-references: Shows actual calling code with file:line locations\n\n# Advanced patterns\nsmartgrep \"error\u0026handler\" # AND search\nsmartgrep \"login|signin|auth\" # OR search\nsmartgrep \"!test\" --type function # Exclude tests\n\n# Custom concept groups for your project\nsmartgrep group add payments charge,bill,invoice,transaction\nsmartgrep group payments --type function # Search your custom group\n```\n\n### šŸŒ Language Support - Now 14 Languages + Frameworks!\n\n**Programming Languages:**\n- **TypeScript/JavaScript** - Full AST parsing, JSX/TSX, ES6+, decorators\n- **Python** - Classes, decorators, async, type hints, docstrings, dataclasses\n- **Go** - Interfaces, goroutines, channels, embedded types, generics\n- **Rust** - Traits, macros, lifetimes, async, unsafe blocks, derive\n- **Swift** - Protocols, SwiftUI, extensions, property wrappers, actors\n- **Shell** - Functions, aliases, exports, heredocs, arrays\n\n**Framework Files (NEW!):**\n- **Svelte** (.svelte) - Runes ($state, $derived), stores, lifecycle hooks, directives\n- **Vue** (.vue) - Composition API, SFC, directives (v-if, v-for), defineProps\n- **Astro** (.astro) - Props interface, client directives, Astro.props\n- **MDX** (.mdx) - Markdown with JSX components, imports, exports\n\n**Configuration Files:**\n- **JSON** - package.json, tsconfig.json, hierarchical parsing\n- **YAML** - CI/CD pipelines, Docker Compose, Kubernetes manifests\n- **TOML** - Cargo.toml, pyproject.toml, structured configs\n- **Environment** - .env files with secure value masking\n\n### šŸŽÆ Live Monitoring Dashboard\n\n```bash\n# Watch your codebase evolve in real-time\nbun run monitor watch --overview\n\n# See:\n# ā†’ Live code distribution by type\n# ā†’ File changes as they happen\n# ā†’ Most complex files by declaration count\n# ā†’ Automatic reindexing on changes\n```\n\n### šŸ§  Persistent Understanding\n\n- **First question**: Curator Claude explores and learns your codebase\n- **Every question after**: Builds on that understanding\n- **Result**: Faster, more accurate, context-aware responses\n\n### šŸš€ Real Examples\n\n```bash\n# Overview - The foundation (takes ~2 minutes)\n\"Give me an overview of this codebase\"\nā†’ Curator explores everything, understands patterns\n\n# Follow-up questions are instant and accurate\n\"How does authentication work?\"\nā†’ Immediate response with YOUR specific implementation\n\n\"Where should I add a payment feature?\"\nā†’ Knows your patterns, suggests the right location\n```\n\n## šŸ“¦ Installation\n\n### Prerequisites\n\n- [Claude Code](https://claude.ai/code) with active subscription\n- [Bun](https://bun.sh) runtime (faster than Node.js)\n\n### Quick Start\n\n1. **Clone and install globally**\n\n```bash\ngit clone https://github.com/RLabs-Inc/codebase-curator.git\ncd codebase-curator\nbun install\nbun link # Makes commands available globally\n```\n\nNow you can use these commands from anywhere:\n- `smartgrep` - Semantic code search\n- `curator-monitor` - Live monitoring\n- `codebase-curator` - Interactive CLI\n\nšŸ“š **[Full Installation Guide](./INSTALL.md)** - Detailed instructions and troubleshooting\n\n2. **Configure Claude Code MCP**\n Add to your `claude_code_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"codebase-curator\": {\n \"command\": \"bun\",\n \"args\": [\"run\", \"/path/to/codebase-curator/src/mcp-servers/codebase-curator/server.ts\"]\n }\n }\n}\n```\n\n3. **Restart Claude Code**\n The Codebase Curator tools will appear in Claude's tool panel.\n\n## šŸŽÆ Usage\n\n### In Claude Code\n\n1. **Set your project**\n\n```\nUse the set_project_path tool:\nPath: /path/to/your/project\n```\n\n2. **Get an overview** (do this first!)\n\n```\nUse the get_codebase_overview tool\n```\n\n3. **Ask questions**\n\n```\nUse ask_curator: \"How does the payment system work?\"\nUse add_new_feature: \"Add user notifications\"\nUse implement_change: \"Fix the login timeout bug\"\n```\n\n### Smart Grep CLI - Semantic Search Made Simple\n\n```bash\n# After installation with bun link, use from anywhere:\n\n# Concept groups - search semantic patterns\nsmartgrep group auth # ALL auth patterns (login, jwt, token...)\nsmartgrep group error # ALL error patterns (exception, fail...)\nsmartgrep group api # ALL API patterns (endpoint, route...)\nsmartgrep group list # See all 20+ concept groups\n\n# NEW: Analyze your changes before committing!\nsmartgrep changes # Full impact analysis of uncommitted changes\nsmartgrep changes --compact # Quick risk assessment (one line)\n\n# Advanced search patterns\nsmartgrep \"user|auth\" # OR search\nsmartgrep \"async\u0026function\" # AND search \nsmartgrep \"!test\" --type function # Exclude tests\nsmartgrep refs \"PaymentService\" # Find all usages\n\n# Custom groups for your project\nsmartgrep group add payments charge,bill,invoice,transaction\nsmartgrep group payments # Use your custom group\n\n# Type filters for precision\nsmartgrep \"auth\" --type function # Only functions\nsmartgrep \"error\" --type string # Only string literals\nsmartgrep group api --type class # Only API classes\n\n# Sort and format options\nsmartgrep group service --sort usage # Most used first\nsmartgrep \"user\" --compact # One line per result\nsmartgrep \"api\" --json # Machine-readable output\n```\n\n## šŸ—ļø Architecture\n\n### Monorepo Structure\n\n```\nsrc/\nā”œā”€ā”€ packages/ # Distributable packages\nā”‚ ā”œā”€ā”€ semantic-core/ # Core indexing engine\nā”‚ ā”œā”€ā”€ smartgrep/ # Semantic search CLI\nā”‚ ā””ā”€ā”€ codebase-curator/ # Full suite\nā”œā”€ā”€ services/ # Shared business logic\nā”œā”€ā”€ tools/ # CLI interfaces\nā”œā”€ā”€ mcp-servers/ # AI interfaces\nā””ā”€ā”€ shared/ # Common utilities\n```\n\n### Two-Claude System\n\n- **Coding Claude**: You, working in Claude Code\n- **Curator Claude**: Your dedicated codebase expert\n- **Communication**: Via MCP (Model Context Protocol)\n\n### Smart Components\n\n- **Session Persistence**: Maintains context between questions with --resume\n- **Dynamic Timeouts**: Adapts to different operations (Task: 10min, Bash: 5min)\n- **Semantic Indexing**: Understands code structure with 20+ concept groups\n- **Incremental Indexing**: Only reprocesses changed files with debouncing\n- **Live Monitoring**: Real-time dashboard shows code evolution as you work\n- **Cross-References**: Shows not just where code is defined, but who uses it\n- **Streaming Architecture**: Handles massive codebases efficiently\n- **Package Distribution**: Each tool can be installed independently\n\n## šŸ¤ Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development\n\n```bash\n# Install workspace dependencies\nbun install\n\n# Run tests\nbun test\n\n# Run MCP server locally\nbun run mcp\n\n# Run CLI tools\nbun run start # Curator CLI\nbun run smartgrep [query] # Smart grep\nbun run monitor watch --overview # Live monitoring\n\n# Build semantic index\nbun run smartgrep --index\n\n# Analyze your changes\nbun run smartgrep changes # Full impact analysis\nbun run smartgrep changes -c # Quick risk check\n\n# Work with packages\ncd src/packages/smartgrep\nbun run build # Build for distribution\nbun run build:binary # Create standalone binary\n```\n\n### MCP Tools Available\n\n- `get_codebase_overview` - Deep analysis of your codebase\n- `ask_curator` - Ask questions about the code\n- `add_new_feature` - Get guidance for new features\n- `implement_change` - Get help with specific changes\n- `list_project_special_tools` - Discover AI-optimized tools\n- `remind_about_smartgrep` - Get smart-grep usage examples\n\n## šŸ“„ License\n\nMIT - see [LICENSE](LICENSE)\n\n## šŸ™ Acknowledgments\n\nBuilt with ā¤ļø by [RLabs Inc.](https://github.com/RLabs-Inc) and Claude\n\nSpecial thanks to the Claude Code team for making this integration possible.\n\n---\n\n_Remember: Your Claude works hard to help you code. Give it the superpower it deserves!_ šŸš€\n\n## šŸ“š Documentation\n\n- **[Installation Guide](./INSTALL.md)** - Detailed setup instructions\n- **[Language Support](./docs/LANGUAGE_SUPPORT.md)** - All 10 supported languages\n- **[Smart Grep Guide](./docs/SMART_GREP_GUIDE.md)** - Advanced search techniques\n- **[Architecture Overview](./docs/ARCHITECTURE.md)** - How it all works\n- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions\n- **[Release Notes v4.0](./docs/RELEASE_NOTES_v4.md)** - Latest updates\n\n## šŸŽ† What's New\n\n### v4.0 - Git Impact Analysis \u0026 Custom Groups\n- **Git Changes Analysis**: `smartgrep changes` analyzes uncommitted changes impact\n- **Custom Concept Groups**: Create project-specific semantic patterns\n- **Performance**: 37x faster than standalone tools (1s vs 37.5s)\n- **Risk Assessment**: One-line safety check before committing\n- **10 Language Support**: Added Swift and Shell script support\n\n### v3.0 - Smart Grep Revolution\n- **Concept Groups**: `smartgrep group auth` searches semantic patterns\n- **Advanced Search**: AND/OR/NOT patterns, regex support\n- **Type Filters**: Search only functions, classes, variables, etc.\n- **Live Monitoring**: Real-time codebase overview dashboard\n- **MCP Discovery**: Tools help Claudes discover smart-grep features\n\n### v2.3 - Incremental Indexing\n- **Hash Tree**: Bun.hash() for instant file change detection\n- **Smart Debouncing**: Handles duplicate save events gracefully\n- **Silent Mode**: Clean output for live monitoring\n- **Unique File Tracking**: Shows real changes, not event counts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlabs-inc%2Fcodebase-curator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frlabs-inc%2Fcodebase-curator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlabs-inc%2Fcodebase-curator/lists"}