🧠 Codebase Curator

🧠 Codebase Curator

🎁 赠予你的 Claude 深入理解代码库的能力

因为你的 Claude 值得拥有一位代码库专家

什么是 Codebase Curator？

Codebase Curator 改变了 Claude 理解代码的方式。它不再把每个问题都当作孤立的问题，而是为 Claude 提供一位持久、智能的伙伴，深入理解你的整个代码库。

问题

每次你向 Claude 询问代码库相关问题时，它都会从头开始：

• 🔄 反复探索相同的文件
• ⏰ 重新发现代码架构，导致响应缓慢
• 🎯 不同问题之间的理解不一致
• 😕 给出的建议千篇一律，不符合你的模式

解决方案：双 Claude 架构

Codebase Curator 会启动专属的“Curator Claude”，让它成为你自己的代码库专家：

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

✨ 主要功能

🤖 双 Claude 架构

• Curator Claude：专属 AI，成为你自己的代码库专家
• 持久会话：在不同问题之间保留上下文
• 即时追问：第一个问题需要 2 分钟，之后的问题都能即时回答

🔍 Smart Grep——理解代码的语义搜索

🚀 新功能：面向 Claude 的精简模式（上下文用量减少 90%！）

Smart Grep 现在默认使用针对 AI 助手优化的精简摘要模式：

# 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

这对 Claude 有何意义：

• 之前：每次搜索消耗 2000-3000 个 token
• 现在：每次搜索仅消耗 200-300 个 token
• 结果：触及上下文限制前，可进行的搜索次数增加 10 倍！

核心功能

# 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

🌐 语言支持——现已支持 14 种语言和框架！

编程语言：

• TypeScript/JavaScript - 完整的 AST 解析、JSX/TSX、ES6+、装饰器
• Python - 类、装饰器、异步、类型提示、文档字符串、数据类
• Go - 接口、goroutine、通道、嵌入类型、泛型
• Rust - trait、宏、生命周期、异步、不安全代码块、派生
• Swift - 协议、SwiftUI、扩展、属性包装器、actor
• Shell - 函数、别名、导出、heredoc、数组

框架文件（新功能！）：

• Svelte (.svelte) - Runes（$state、$derived）、store、生命周期钩子、指令
• Vue (.vue) - 组合式 API、SFC、指令（v-if、v-for）、defineProps
• Astro (.astro) - Props 接口、客户端指令、Astro.props
• MDX (.mdx) - 搭配 JSX 组件的 Markdown、导入、导出

配置文件：

• JSON - package.json、tsconfig.json、分层解析
• YAML - CI/CD 流水线、Docker Compose、Kubernetes 清单
• TOML - Cargo.toml、pyproject.toml、结构化配置
• 环境变量 - .env 文件，安全地隐藏值

🎯 实时监控面板

# 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

🧠 持久理解

• 第一个问题：Curator Claude 会探索并学习你的代码库
• 之后的每个问题：都在已有理解的基础上回答
• 结果：响应更快、更准确，并能结合上下文

🚀 实例

# 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，并拥有有效订阅
• Bun 运行时（比 Node.js 更快）

快速开始

1. 克隆并进行全局安装

git clone https://github.com/RLabs-Inc/codebase-curator.git
cd codebase-curator
bun install
bun link  # Makes commands available globally

现在，你可以在任何位置使用以下命令：

• smartgrep - 语义代码搜索
• curator-monitor - 实时监控
• codebase-curator - 交互式命令行

📚 完整安装指南 - 详细说明和故障排除

2. 配置 Claude Code MCP 添加到你的 claude_code_config.json 中：

{
  "mcpServers": {
    "codebase-curator": {
      "command": "bun",
      "args": ["run", "/path/to/codebase-curator/src/mcp-servers/codebase-curator/server.ts"]
    }
  }
}

3. 重启 Claude Code Codebase Curator 工具将显示在 Claude 的工具面板中。

🎯 使用方法

在 Claude Code 中

1. 设置项目

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

2. 获取概览（首先执行此步骤！）

Use the get_codebase_overview tool

3. 提问

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 - 让语义搜索变得简单

# 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

🏗️ 架构

Monorepo 结构

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

双 Claude 系统

• 编码 Claude：你，在 Claude Code 中工作
• 策展 Claude：专属的代码库专家
• 通信：通过 MCP（Model Context Protocol）

智能组件

• 会话持久化：使用 --resume 在问题之间保留上下文
• 动态超时：根据不同操作进行调整（Task：10min，Bash：5min）
• 语义索引：通过 20 多个概念组理解代码结构
• 增量索引：通过防抖机制，仅重新处理变更的文件
• 实时监控：实时仪表板会随你的工作展示代码的演变
• 交叉引用：不仅显示代码定义的位置，还显示使用它的代码
• 流式架构：高效处理大型代码库
• 软件包分发：每个工具都可以单独安装

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

开发

# 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 工具

• get_codebase_overview - 深入分析你的代码库
• ask_curator - 询问有关代码的问题
• add_new_feature - 获取新功能的指导
• implement_change - 获取特定变更方面的帮助
• list_project_special_tools - 发现针对 AI 优化的工具
• remind_about_smartgrep - 获取 smart-grep 用法示例

📄 许可证

MIT - 参见 LICENSE

🙏 致谢

由 RLabs Inc. 和 Claude 倾力打造 ❤️

特别感谢 Claude Code 团队促成这项集成。

---

请记住：你的 Claude 努力帮助你编写代码。赋予它应有的超能力吧！ 🚀

📚 文档

• 安装指南 - 详细的设置说明
• 语言支持 - 全部 10 种受支持的语言
• Smart Grep 指南 - 高级搜索技巧
• 架构概览 - 了解整体工作原理
• 故障排除 - 常见问题及解决方案
• v4.0 发行说明 - 最新更新

🎆 新功能

v4.0 - Git 影响分析与自定义组

• Git 变更分析：smartgrep changes 可分析未提交变更的影响
• 自定义概念组：创建项目专属的语义模式
• 性能：速度比独立工具快 37 倍（1s 对比 37.5s）
• 风险评估：提交前进行单行安全检查
• 支持 10 种语言：新增 Swift 和 Shell 脚本支持

v3.0 - Smart Grep 革新

• 概念组：smartgrep group auth 可搜索语义模式
• 高级搜索：支持 AND/OR/NOT 模式和正则表达式
• 类型筛选器：仅搜索函数、类、变量等
• 实时监控：实时代码库概览仪表板
• MCP 发现：工具可帮助 Claude 发现 smart-grep 功能

v2.3 - 增量索引

• 哈希树：使用 Bun.hash() 即时检测文件变更
• 智能防抖：妥善处理重复的保存事件
• 静默模式：为实时监控提供简洁输出
• 唯一文件跟踪：展示实际变更，而非事件计数