codeseeker

CodeSeeker

AI コーディングアシスタント向けの4層ハイブリッド検索とナレッジグラフです。
BM25 ＋ ベクトル埋め込み ＋ RAPTOR ディレクトリ要約 ＋ グラフ拡張を単一の MCP ツールに統合し、Claude、Copilot、Cursor にコードベースを的確に理解させます。

Claude Code、GitHub Copilot（VS Code 1.99+）、Cursor、Windsurf、Claude Desktopに対応しています。
インデックス作成は1つのコマンドで完了し、その後は Claude Code プラグインが同期を維持します。

PragmaWorks が Generative Specification の一環として開発しました。これは、AI を使ってぶれのないソフトウェアを構築するための 規律です。2つの姉妹 MCP サーバーがこのサーバーと連携し、それぞれ同じ問題の異なる半分を解決します。

これらは独立しているため、1つだけでも、3つすべてでもインストールできます。

これが不要になるとき

CodeSeeker は検索の問題を解決しますが、その問題は小さくなりつつあります。

実際に使えるハーネスを備えた仕様駆動のループ、つまり、ステートレスなモデルが仕様から導出できるほど精密な仕様と、稼働中の システムに対して結果を検証する品質ゲートを使っている場合、あるいは意図駆動のループを使っている場合、アシスタントには、そうでなければ自ら探しに行かなければならない構造があらかじめ渡されています。多数のエンドポイントにまたがって処理を広げるのではなく、アクションを振り分けるセンチネルツールを使えば、検索する必要はさらに減ります。より優れたナビゲーション能力と、より大きな実効コンテキストを備えた最先端モデルによって、その必要性はさらに低下します。ある段階を過ぎると、自分のコードに対するセマンティック検索はボトルネックではなくなり、このサーバーをアンインストールしても気づかないほどになります。

それは欠陥ではなく、意図した結果です。うまく機能する手法は、いずれ自らの足場を不要にします。ただし、ほとんどのチームはそこから始めるわけではありません。プロセスが整うまでは、CodeSeeker がより安価な代替手段となります。規律の代わりに、コマンド1つで済みます。

代替手段ではなくプロセスを選ぶ場合は、フィールドガイドをご覧ください。 Generative Specification — Field Guide（PDF）。

問題

AI アシスタントは強力なエディターですが、コード内を観光客のように探索します。

• Grep が見つけるのはテキストであり、意味ではありません。「authentication logic を探して」と指定すると、「auth」という単語を含むすべてのファイルが返されます
• ファイルの読み込みは個別に行われます。Claude はファイルを見ても、その依存関係、呼び出し元、チームで確立したパターンまでは把握できません
• プロジェクトの記憶がありません。セッションのたびに、すべてが最初から始まります

CodeSeeker はこれを解決します。コードベースを一度インデックス化し、AI アシスタントが毎回のやり取りで利用できる、クエリ可能なナレッジグラフを提供します。

仕組み

すべてのクエリで、4段階のパイプラインが実行されます。

Query: "find JWT refresh token logic"
        │
        ▼  Stage 1 — Hybrid retrieval
   ┌─────────────────────────────────────────────────────┐
   │ BM25 (exact symbols, camelCase tokenized)           │
   │   +                                                 │
   │ Vector search (384-dim Xenova embeddings)           │
   │   ↓                                                 │
   │ Reciprocal Rank Fusion: score = Σ 1/(60 + rank_i)  │
   │ Top-30 results, including RAPTOR directory nodes    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 2 — RAPTOR cascade (conditional)
   ┌─────────────────────────────────────────────────────┐
   │ IF best directory-summary score ≥ 0.5:              │
   │   → narrow results to that directory automatically  │
   │ ELSE: all 30 results pass through unchanged         │
   │ Effect: "what does auth/ do?" scopes to auth/       │
   │         "jwt.ts decode function" bypasses this      │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 3 — Scoring and deduplication
   ┌─────────────────────────────────────────────────────┐
   │ Dedup: keep highest-score chunk per file            │
   │ Source files:  +0.10  (definition sites matter)     │
   │ Test files:    −0.15  (prevent test dominance)      │
   │ Symbol boost:  +0.20  (query token in filename)     │
   │ Multi-chunk:   up to +0.30  (file has many hits)    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 4 — Graph expansion
   ┌─────────────────────────────────────────────────────┐
   │ Top-10 results → follow IMPORTS/CALLS/EXTENDS edges │
   │ Structural neighbors scored at source × 0.7        │
   │ Avg graph connectivity: 20.8 edges/node             │
   └─────────────────────────────────────────────────────┘
        │
        ▼
   auth/jwt.ts (0.94), auth/refresh.ts (0.89), ...

ナレッジグラフは、インデックス作成時に AST で解析したインポート情報から構築されます。これにより、graph アクション、未使用コードの検出、すべての検索におけるグラフ拡張が実現します。

他との違い

LSP ツールではできないこと：

• 「このようなエラーを処理するコードを見つけて」 → セマンティックなパターン検索
• 「このプロジェクトではどのような検証方法を使っていますか？」 → コーディング規約を自動検出
• 「認証に関係するものをすべて表示して」 → 間接的な依存関係をまたいだグラフ探索

ベクトル検索のみでは見落とすもの：

• 直接的なインポート／エクスポートの連鎖
• クラスの継承階層
• どのファイルが実際にどのファイルに依存しているか

インストール

推奨：一度インストールして、一度設定する

npm install -g codeseeker
claude mcp add codeseeker --scope user -e CODESEEKER_STORAGE_MODE=embedded -- codeseeker serve --mcp

--scope user を指定すると、現在のプロジェクトだけでなく、開くすべてのプロジェクトで利用できるようになります。

npx -y ではなくグローバルインストールを推奨する理由： このパッケージを一度も使用したことのないマシンでは、サーバーが応答する前に npx がパッケージをダウンロードし、ネイティブ依存関係をビルドします。MCP ハンドシェイクが完了するまでに、実測で13.7 秒かかりました。それより早く処理を打ち切るクライアントでは、接続エラーとして報告されます。グローバルインストールなら759 ミリ秒で応答します。ダウンロードは、時間に余裕があるときに一度だけ行われます。

npx（インストール不要）

ポータブルで、パッケージがキャッシュされていれば問題なく使えます。初回起動には時間がかかります。

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"],
      "env": { "CODESEEKER_STORAGE_MODE": "embedded" }
    }
  }
}

これを MCP 設定ファイルに追加し（クライアントごとの場所はこちらを参照）、エディターを再起動してください。

その他のエディター

npm install -g codeseeker
codeseeker install --vscode      # or --cursor, --windsurf, --vs

🔌 Claude Code プラグイン

Claude Code CLI ユーザー向けです。自動同期フックとスラッシュコマンドが追加されます。

/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin

スラッシュコマンド：/codeseeker:init、/codeseeker:reindex

☁️ Devcontainers / GitHub Codespaces

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "postCreateCommand": "npm install -g codeseeker && codeseeker install --vscode"
}

✅ 確認

AI アシスタントに次のように尋ねてください：「利用できる CodeSeeker ツールは何ですか？」

codeseeker という名前のツールが 1 つ表示されます。これは意図的な設計です。action ルーティングキーを使って 1 つのツールにまとめることで、リクエストごとのトークンオーバーヘッドを低く抑えています（ADR-002）。アクションは search、sym、graph、analyze、index です。

高度なインストールオプション

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"]
    }
  }
}

npm install -g codeseeker
cd your-project
codeseeker init
codeseeker -c "how does authentication work in this project?"

CodeSeeker が公開する MCP ツールは codeseeker 1 つだけです。action で動作を選び、対応するネストされたパラメーターグループのみを指定します。

codeseeker({ action, project, search?|sym?|graph?|analyze?|index? })

必ず project（プロジェクトの絶対パス）を渡してください。MCP サーバーは作業ディレクトリを検出できません。

これらを手動で呼び出す必要はありません。Claude はコードの検索や関連性の分析時に自動で使用します。

インデックス作成の仕組み

事前にインデックスを作成する必要はありません。 CodeSeeker がまだ認識していないプロジェクトを検索すると、自動的にインデックス作成が始まり、そのことが通知されます。インデックス作成はバックグラウンドで実行されるため、アシスタントを待たせずに呼び出しはすぐに戻ります。

User: "Find the authentication logic"
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ Claude calls codeseeker({action:"search"})             │
│         │                                              │
│         ▼                                              │
│ Project indexed? ──No──► starts indexing, returns      │
│         │                {status:"indexing_started"}   │
│        Yes                                             │
│         ▼                                              │
│ Return ranked results + confidence                     │
└────────────────────────────────────────────────────────┘

そのため、新しいプロジェクトについて最初に質問したときは、検索結果ではなく「インデックス作成を開始しました。少し待ってから再試行してください」と返されます。小規模なプロジェクトなら数秒、大規模なプロジェクトでは数分かかります。 推測せずに index({op:"status"}) で確認してください。

手動でインデックスを作成することもできます。大規模なリポジトリでは、待ち時間を都合のよいタイミングにできるため、手動での作成がおすすめです。

codeseeker({ action: "index", index: { op: "init", path: "/abs/path", name: "my-project" } })

codeseeker init          # or, from the CLI

明示的な初期化で name を指定すると、自動処理では分からないプロジェクト名を登録できます。それ以外の場合、プロジェクトはディレクトリ名で登録されます。

インデックスを最新の状態に保つ

インデックスはスナップショットです。ファイルシステムは監視されないため、ファイルの変更後に最新の状態へ戻す方法は 3 つあります。

プラグインを使わない場合、古くなったインデックスでも検索結果は返され続けます。ただし、その結果は以前のコードに基づくものです。これを知らせるのが stale_index シグナルです。

検索品質の研究

npm run build
node scripts/real-bench.js

自動検出されるコーディング規約

CodeSeeker はコードベースを分析し、パターンを抽出します：

{
  "validation": {
    "email": {
      "preferred": "z.string().email()",
      "usage_count": 12,
      "files": ["src/auth.ts", "src/user.ts"]
    }
  },
  "react-patterns": {
    "state": {
      "preferred": "useState<T>()",
      "usage_count": 45
    }
  }
}

検出されるパターンのカテゴリ：

• validation：Zod、Yup、Joi、validator.js、カスタム正規表現
• error-handling：API エラーレスポンス、try-catch パターン、カスタム Error クラス
• logging：Console、Winston、Bunyan、構造化ログ
• testing：Jest/Vitest の設定、アサーションパターン
• react-patterns：フック（useState、useEffect、useMemo、useCallback、useRef）
• state-management：Redux Toolkit、Zustand、React Context、TanStack Query
• api-patterns：Fetch、Axios、Express ルート、Next.js API ルート

Claude が新しいコードを記述するときは、新しい規約を作り出すのではなく、既存の規約に従います。

インデックス除外の管理

Claude がインデックスに含めるべきでないファイル（Unity の Library フォルダー、ビルド出力、生成ファイルなど）を検出した場合、動的に除外できます：

// Exclude Unity Library folder and generated files
codeseeker({
  action: "index",
  project: "/abs/path/to/my-unity-game",
  index: {
    op: "exclude",
    exclude_op: "exclude",
    paths: ["Library/**", "Temp/**", "*.generated.cs"],
    reason: "Unity build artifacts"
  }
})

除外設定は .codeseeker/exclusions.json に保存され、再インデックス時に自動的に適用されます。

コードクリーンアップツール

CodeSeeker は、重複コードの検索やデッドコードの検出によって、コードベースをクリーンに保つのに役立ちます。

重複コードの検索

統合できる類似コードブロックを検索するよう Claude に依頼します：

"Find duplicate code in my project"
"Are there any similar functions that could be merged?"
"Show me copy-pasted code that should be refactored"

CodeSeeker はベクトル類似度を使って、完全一致だけでなく、意味的に類似するコードを検索します。次のようなものを検出します：

• わずかな違いがあるコピー＆ペーストされた関数
• ファイル間で類似するバリデーションロジック
• ユーティリティに抽出できる繰り返しパターン

デッドコードの検索

安全に削除できる未使用コードを特定するよう Claude に依頼します：

"Find dead code in this project"
"What functions are never called?"
"Show me unused exports"

CodeSeeker はナレッジグラフを分析し、次のものを検索します：

• 一度もインポートされていないエクスポート済み関数／クラス
• 呼び出し元のない内部関数
• 依存関係が参照されていない孤立ファイル

ワークフローの例：

User: "Use CodeSeeker to clean up this project"

Claude: I'll analyze your codebase for cleanup opportunities.

Found 3 duplicate code blocks:
- validateEmail() in auth.ts and user.ts (92% similar)
- formatDate() appears in 4 files with minor variations
- Error handling pattern repeated in api/*.ts

Found 2 dead code files:
- src/utils/legacy-helper.ts (0 imports)
- src/services/unused-service.ts (exported but never imported)

Would you like me to:
1. Consolidate the duplicate validators into a shared utility?
2. Remove the dead code files?

言語サポート

すべての言語がインデックス化され、検索可能です。チャンク分割と埋め込みはパーサーに依存しません。パーサーによって変わるのはナレッジグラフ、つまり CodeSeeker がシンボルを宣言としてどれだけ正確に把握し、何が何に依存しているかをどれだけ正確に把握するかです。

Regex による抽出は、同じ機能の簡易版ではなく、実質的な制限があります。 宣言の形状から検出するため、通常とは異なる書き方は見逃し、宣言と呼び出しを区別できません。インポートのエッジは、Babel が解析する TypeScript と JavaScript では引き続き信頼できますが、呼び出しのエッジはすべての言語でヒューリスティックです。

上記の評価は、推測ではなく測定結果です。scripts/corpus-bench.js は実際の 7 つのプロジェクトをインデックス化し、scripts/graph-quality.js は生成された各グラフのうち、実際の宣言である可能性が高いものの割合を報告します。Java はコーパスに Java プロジェクトがないため独自の評価はありません。Python と同じ Tree-sitter のコードパスを共有しており、主張できるのはそのことだけです。

4 つの RealWorld Conduit 実装で測定しました。同じアプリケーションを 4 回実装したものなので、実装間の差はタスクの難易度ではなく言語処理によるものです。30 件のラベル付きクエリに対する平均逆順位は、TypeScript が 83.3%、Python が 81.5%、JavaScript が 77.1%、C# が 70.5% です。

使用言語のパーサーを追加する

プロジェクトの大部分が Go、Rust、C++、または Ruby であれば、その言語の Tree-sitter 文法をインストールできます。

npm install -g tree-sitter-go        # or tree-sitter-rust, tree-sitter-cpp, …

次に、アシスタントに依頼するか、以下を実行します。

codeseeker({ action: "index", project: "/abs/path", index: { op: "parsers", list_available: true } })

応答では、各パーサーが wired: true または wired: false と示されます。グラフビルダーが使用するのは wired: true と示されたパーサーだけです。false と示されたパーサーをインストールしても現時点では何も変わりません。改善に気づかずに終わることがないよう、応答でそのことを明示します。

現在対応済み：TypeScript、JavaScript、Python、Java、C#。その他は正直に false と表示されます。対応させるための変更は小規模で完結しています。ILanguageParser を実装するパーサーを extensionToParser に登録します（src/mcp/indexing-service.ts）。コントリビューションを歓迎します。scripts/graph-quality.js を使えば、新しいパーサーによってグラフが実際に改善したかを測定できるため、改善を推測ではなく実証できます。

インデックスを同期した状態に保つ

Claude Code プラグインを使用する場合

プラグインは、インデックスを自動的に更新するフックをインストールします。

何もする必要はありません。プラグインが自動的に同期を処理します。

MCP サーバーのみを使用する場合（Cursor、Claude Desktop）

• Claude が開始する変更：Claude は codeseeker({action:"index", index:{op:"sync"}}) を呼び出せます
• 手動での変更：自動検出されません。定期的に再インデックスするよう Claude に依頼してください

同期の概要

CodeSeeker が最も役立つ場面

適しているケース：

• 1 万を超えるファイルがあり、Claude が関連するコードを見つけるのに苦労する大規模なコードベース
• Claude に従ってほしい既存のパターンが確立されているプロジェクト
• 複数のファイルにまたがる複雑な依存関係
• AI が生成するコードの一貫性を求めるチーム

あまり役立たないケース：

• 既存のコードがほとんどない新規プロジェクト
• 単一ファイルのスクリプト
• アーキテクチャを積極的に変更しているプロジェクト

アーキテクチャ

┌──────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                         │                                │
│                    MCP Protocol                          │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │              CodeSeeker MCP Server               │    │
│  │  ┌─────────────┬─────────────┬────────────────┐ │    │
│  │  │   Vector    │  Knowledge  │    Coding      │ │    │
│  │  │   Search    │    Graph    │   Standards    │ │    │
│  │  │  (SQLite)   │  (SQLite)   │   (JSON)       │ │    │
│  │  └─────────────┴─────────────┴────────────────┘ │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘

すべてのデータはローカルの .codeseeker/ に保存されます。外部サービスは必要ありません。

大規模なチーム（10 万ファイル以上、共有インデックス）では、サーバーモードで PostgreSQL と Neo4j をサポートしています。ストレージのドキュメントを参照してください。

技術的な内部構造の完全な説明（正確なスコア計算式、MCP ツールのスキーマ、グラフのエッジタイプ、RAPTOR のしきい値ロジック、パイプラインの各段階、分析の信頼度レベル）については、**技術アーキテクチャマニュアル**を参照してください。

トラブルシューティング

MCP サーバーに接続できない

1. npm と npx が動作することを確認します：npx -y codeseeker --version
2. MCP 設定ファイルの構文を確認します（有効な JSON であること、末尾にカンマがないこと）
3. エディターまたは Claude アプリケーションを完全に再起動します
4. Node.js がインストールされていることを確認します：node --version（v18 以降が必要です）

インデックス作成が遅いように見える

大規模なプロジェクト（5 万ファイル以上）の初回インデックス作成には、5 分以上かかることがあります。2 回目以降はすぐに完了します。

Claude にツールが表示されない

1. Claude に「利用できる CodeSeeker ツールを教えてください」と尋ねます
2. ツールが表示されない場合は、MCP 設定ファイルが存在し、構文が正しいことを確認します
3. IDE を完全に再起動します（ウィンドウを再読み込みするだけでは不十分です）
4. IDE で Claude／Copilot の MCP 接続ステータスを確認します

それでも解決しない場合

問題を報告してください：GitHub の問題

ドキュメント

• 統合ガイド - すべてのコンポーネントの接続方法
• アーキテクチャ - 技術的な詳細
• CLI コマンド - コマンドの完全なリファレンス

対応プラットフォーム

Claude Code と GitHub Copilot は同じ .vscode/mcp.json を共有します。一度設定すれば、両方で動作します。

サポート

CodeSeeker が役に立った場合は、プロジェクトへのスポンサーをご検討ください。

ライセンス

Apache License 2.0。 LICENSE と NOTICE を参照してください。

商用利用を含め、あらゆる用途で無料で利用できます。企業規模や売上に関する制限はありません。Apache-2.0 は MIT よりも明示的な特許許諾を含むため、ここでは Apache-2.0 を採用しています。

チームで CodeSeeker を実行する

上記はすべて、ローカルでの単独開発者向けセットアップです。インデックスはお使いのマシン上の .codeseeker/ に保存され、外部に持ち出されることはありません。

チーム向けには、一元化されたデプロイ方法があります。組織のリポジトリを対象とする共有インデックス（PostgreSQL + pgvector、Neo4j）を使用することで、各エンジニアが同じコードのインデックスを個別に作成する必要がなくなり、グラフが 1 つのリポジトリで途切れることなく、サービス間にまたがるようになります。また、ローカルツールでは構造上把握できない情報、つまりコードベース全体でコードの理解が実際にどのように分散しているか、どこに知識のギャップがあるかも明らかにします。

チームに役立ちそうな場合は、お問い合わせください：https://pragmaworks.dev

CodeSeeker は、grep と埋め込みだけでは提供できないコードの理解を Claude にもたらします。

生成仕様の一部

**Generative Specification（GS）**を支える Apache-2.0 のツールです。GS とは、AI でソフトウェアを構築する際に、仕様から逸脱しないようにする分野です。ステートレスな AI が正しいコードを仕様から導き出せるほど精密な仕様を作成し、ハーネスで稼働中のシステムに対して検証します。

• 📄 ホワイトペーパー（無料公開）：https://doi.org/10.5281/zenodo.21726017
• 📕 フィールドガイド — 短く実践的な入門ガイド：https://github.com/jghiringhelli/generative-specification/blob/main/docs/white-paper/GenerativeSpecification_FieldGuide.pdf
• 🧭 まずはこちら — 手法、ツール、利用者の声：https://pragmaworks.dev
• 🔨 The Forge — チーム向けの2日間のGS実践ワークショップ：https://forgeworkshop.dev