🧠 Codebase Curator

🧠 Codebase Curator

🎁 Claude に、コードベースを深く理解する力をプレゼントしましょう

Claude のそばにコードベースの専門家がいれば、もっと頼もしくなります

Codebase Curator とは？

Codebase Curator は、Claude がコードを理解する方法を変えます。質問ごとに個別に対応するのではなく、コードベース全体を深く理解する、永続的で高性能なパートナーを Claude に提供します。

問題点

コードベースについて Claude に質問すると、毎回ゼロから調査を始めます。

• 🔄 同じファイルを繰り返し調査する
• ⏰ アーキテクチャを再発見するため、回答が遅くなる
• 🎯 質問ごとに理解が一貫しない
• 😕 コードのパターンに合わない一般的な提案が返される

解決策：2つの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

✨ 主な機能

🤖 2つの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トークンを消費
• 現在：検索ごとにわずか200～300トークン
• 結果：コンテキスト上限に達するまでに、検索回数が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 - クラス、デコレーター、非同期処理、型ヒント、docstring、データクラス
• Go - インターフェース、goroutine、チャネル、埋め込み型、ジェネリクス
• Rust - トレイト、マクロ、ライフタイム、非同期処理、unsafeブロック、derive
• Swift - プロトコル、SwiftUI、拡張、プロパティラッパー、アクター
• Shell - 関数、エイリアス、エクスポート、ヒアドキュメント、配列

フレームワークのファイル（新機能！）：

• Svelte (.svelte) - Runes（$state、$derived）、ストア、ライフサイクルフック、ディレクティブ
• Vue (.vue) - Composition 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 がコードベースを調査し、学習します
• 2回目以降の質問：その理解を基に回答を重ねます
• 結果：より高速で、より正確な、コンテキストを考慮した回答

🚀 実例

# 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 - 対話型CLI

📚 インストールガイド全文 - 詳細な手順とトラブルシューティング

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

🏗️ アーキテクチャ

モノレポ構成

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

2つの Claude システム

• コーディング Claude：Claude Code で作業するあなた
• キュレーター Claude：専任のコードベースエキスパート
• 通信：MCP（Model Context Protocol）経由

スマートなコンポーネント

• セッションの永続化：--resume を使って質問間のコンテキストを維持します
• 動的なタイムアウト：さまざまな操作に合わせて調整します（Task：10分、Bash：5分）
• セマンティックインデックス作成：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倍高速です（1秒対37.5秒）
• リスク評価：コミット前に1行で安全性を確認できます
• 10言語をサポート：Swift と Shell スクリプトのサポートを追加しました

v3.0 - Smart Grep の革新

• コンセプトグループ：smartgrep group auth でセマンティックパターンを検索します
• 高度な検索：AND／OR／NOT パターン、正規表現をサポートします
• 型フィルター：関数、クラス、変数などに絞って検索します
• ライブモニタリング：コードベースの概要をリアルタイムダッシュボードで表示します
• MCP による検出：ツールが Claude に smart-grep の機能を見つける手助けをします

v2.3 - 増分インデックス作成

• ハッシュツリー：ファイルの変更を即座に検出する Bun.hash()
• スマートなデバウンス処理：重複する保存イベントを適切に処理します
• サイレントモード：ライブモニタリング用に出力をすっきりさせます
• 一意なファイルの追跡：イベント数ではなく、実際の変更を表示します