BeaconBay/ck

Local first semantic and hybrid BM25 grep / search tool for use by AI and humans!

📦 ck – 意味ベースのコード検索

ck（読み："seek"）は、Rustで作られたコマンドラインツールで、コードを意味で検索できるようにします。文字列の一致だけでなく、概念を理解して検索します。コードのローカル埋め込みを構築し、インクリメンタルにキャッシュし、エラー処理や認証ロジックといったキーワードが存在しない場合でも、関連する関数、クラス、コードブロックを検索できます。

🎯 機能

機能	機能内容
意味ベース検索	ベクトル埋め込み（BGE‑Small、Mixedbread、Nomic、Jina‑Codeなど）を使ってコードの概念を検索。
ハイブリッド検索	類似度スコアと従来の正規表現/キーワードマッチングを組み合わせ、Reciprocal Rank Fusionで統合。
grep互換CLI	`grep`/`ripgrep`と同様のフラグ（`-n`, `-R`, `-l`など）をサポート。
インタラクティブTUI	フルスクリーン端末UI、リアルタイム結果表示、プレビュー、マルチセレクト、エディタ連携。
AIエージェント（MCP）サーバー	Model Context Protocol（MCP）経由で`semantic_search`、`regex_search`などのツールを公開。Claude Desktop、Cursor、その他のエージェントがプログラム的に呼び出せる。
インクリメンタル・チャンクレベルインデックス	変更されたチャンクのみ再埋め込み。通常の編集でキャッシュヒット率は80–90％。
スマートなファイルフィルタリング	`.gitignore`、専用の`.ckignore`、コマンドラインの除外フラグを尊重。
構造化出力	`--json`（単一配列）または`--jsonl`（行区切り）でスクリプトやLLMパイプラインに最適。
多言語対応	Python、JavaScript/TypeScript、Rust、Go、C/C++、C#、Ruby、Haskell、Dart、Markdown、および汎用テキスト形式。
オフライン専用	すべての埋め込みモデルはローカルで実行。初期モデルダウンロード後はネットワーク通信なし。

⚙️ 動作原理（概要）

インデックス作成 – ck --index <root> でソースツリーを走査し、Tree‑sitterを使って言語に適したチャンク（関数、クラスなど）に分割。FastEmbedで埋め込みを計算。インデックスデータは.ck/ディレクトリ（またはCK_INDEX_DIRでカスタム）に保存。
検索 – クエリは同じモデルで埋め込み、保存されたベクトルとの類似度スコアを計算。ハイブリッドモードでは、並行して従来の正規表現検索を実行し、2つの結果リストを統合。
サーバー起動 – ck --serve でMCPサーバーを起動。検索ツールをJSON-RPCエンドポイントとして公開し、AIアシスタントが直接呼び出せるようにする。

🚀 クイックスタート（CLI）

# crates.ioからバイナリをインストール
cargo install ck-search

# 意味ベース検索（初回実行時にインデックス自動作成）
ck --sem "error handling" src/

# ハイブリッド検索（意味 + キーワード）
ck --hybrid "connection timeout" src/

# 伝統的なgrepスタイル検索
ck -R "TODO|FIXME" .

# インタラクティブTUI
ck --tui "authentication logic"

🤖 AIエージェント統合（MCP）

# サーバー起動
ck --serve

サーバーはsemantic_searchなどのツールを登録し、エージェントが呼び出せるようになります：

{
  "tool": "semantic_search",
  "args": {"query": "authentication logic", "path": "/my/project", "top_k": 25}
}

レスポンスはJSONL形式でストリーミングされ、LLM駆動のワークフローで簡単に処理可能。

📚 一般的な利用シーン

開発生産性向上 – 精確な識別子を覚えていなくても、概念の実装にすぐジャンプ。
コードレビュー準備 – セキュリティに重要なパターンを実装するすべての関数を一覧。
CI/CD自動化 – リポジトリ内で不正なパターンをスキャン（ck --json --sem "password|secret" . | my_scanner）。
チームオンボーディング – 関連するテストファイルや重複するロジックを素早く特定。
LLM強化ツール – 構造化された検索結果をClaude、Cursor、カスタムエージェントに供給。

📦 インストール方法

方法	コマンド
Crates.io（推奨）	`cargo install ck-search`
ソースから	`git clone https://github.com/BeaconBay/ck && cd ck && cargo install --path ck-cli`
将来のパッケージマネージャー	Brew / aptパッケージは計画中だが、まだリリースされていない。

📄 ライセンス

MIT および Apache‑2.0 の二重ライセンス（LICENSE-MIT / LICENSE-APACHE を参照）。

🙏 詳細情報

全ドキュメント: https://beaconbay.github.io/ck/
TUIガイド: リポジトリ内の TUI.md
モデル選択とインデックス詳細はREADMEのテーブルに記載。

ck は、実用的で積極的にメンテナンスされているオープンソースプロジェクト。コマンドラインでのコードgrepに、現代的なAI駆動の意味ベース検索をもたらします。オフラインで動作し、.gitignoreを尊重し、人間のワークフローとAIエージェントの両方にスムーズに統合されます。