Claude CodeのLumenプラグインでコード探索のトークンを減らす — ローカル意味検索の入れ方

Lumenは、コードベースをローカルで意味検索できるようにするClaude Codeのプラグインです。提供元はOry Corpで、Claude Codeのマーケットプレイスには「Precise local semantic code search via MCP」という説明で載っています。クラウドもnpmも使いません。

仕組みは単純です。プロジェクトを関数や型の単位に切り、手元のOllamaかLM Studioで埋め込み、SQLiteに保存します。Claude Codeが何かを調べるとき、ファイルを丸ごと読む代わりにsemantic_searchというMCPツールを呼べるようになります。

この記事では、導入手順、入る中身、索引の置き場所と除外の指定、公開されているベンチマークの読み方、つまずきやすい点を順に説明します。

Lumenは何を足すプラグインか

マーケットプレイスのページによれば、Lumenは「Go ASTの解析でコードベースを索引化し、OllamaまたはLM Studioで埋め込み、MCPサーバー経由でClaudeにベクトル検索を渡す」ものです。ページにはインストール数651と提供元Oryの表記があります。

README側の整理では、主な特徴は次のとおりです。

「トークンを減らす」という狙いは、リポジトリの説明文にある「Claude Codeなどで30%のトークンコストを減らす」という主張に由来します。ただし、これは提供元の主張です。どの条件でどれだけ下がったかは、後述のベンチマークの節で数字と条件を分けて読みます。

入れる前に用意するもの

前提は2つです。

• Ollamaが入っていて起動していること
• Claude Code、Cursor、Codex、OpenCodeのいずれか

既定の埋め込みモデルはordis/jina-embeddings-v2-base-codeで、先にpullしておきます。

ollama pull ordis/jina-embeddings-v2-base-code

LM Studioを使う場合の既定モデルはnomic-ai/nomic-embed-code-GGUFです。対応OSはLinux、macOS、Windowsで、バックグラウンドの索引化の排他制御にはUnixでflock(2)、WindowsでLockFileExが使われます。

Claude Codeへの入れ方

マーケットプレイスを追加してからプラグインを入れます。Claude Codeのセッション内で実行します。

/plugin marketplace add ory/claude-plugins
/plugin install lumen@ory

入れたあとは、新しいセッションを始めて/lumen:doctorを実行すると状態を確認できます。プラグインの入れ方そのものは、同じ形で配布されている他のプラグインと変わりません。例としてAikidoプラグインの記事も参照できます。

最初のセッション開始時にLumenが行うことは3つです。

1. GitHubの最新リリースからバイナリを自動でダウンロードする
2. Merkleツリーによる変更検出で、プロジェクトをバックグラウンドで索引化する
3. ホストが自動で使えるsemantic_searchというMCPツールを登録する

つまり、バイナリを手でビルドする必要はありません。ソースから試したい場合だけ、リポジトリをcloneしてmake plugin-devでClaude Codeのプラグインとして読み込めます。ビルドにはsqlite-vecのためにCGOが必要です。

同梱のMCPツールとskill

プラグインが公開するのは、MCPツール3つとskill 2つです。

health_checkの役割は、READMEのトラブルシューティングが「Cursor・Codex・OpenCodeではdoctorのskillを使うか、health_checkとindex_statusを直接呼ぶ」と書いていることから、doctorに対応する診断用のツールと読めます。個別の戻り値までは、READMEにありません。

index_statusについては、プロジェクト内のファイル数とチャンク数に加えて、索引全体の一意なベクトル数、共有参照、重複排除率、ベクトルの精度、DBサイズ、回収可能なSQLiteページを報告すると説明されています。

検索はどう進むのか

READMEが示す流れは次のとおりです。

ここで大事なのは「検索はファイルの代わりに候補を絞る」だけという点です。絞った箇所の中身を読む工程は、これまでどおりClaude Codeの通常のファイル読み取りが担います。Lumenが減らそうとしているのは、探すための読み込みです。

索引はどこに置かれ、何が対象になるか

索引の置き場所

索引はプロジェクトの外、~/.local/share/lumen/<hash>/index.dbに置かれます。リポジトリにファイルは追加されません。<hash>はGitの共通ディレクトリ(Gitでないプロジェクトは絶対パス)、索引の範囲、埋め込みモデルと次元数、ベクトル精度、チャンク分割の方針、索引のバージョンから決まります。

そのため、モデルを切り替えるとモデルごとに別の索引ができ、衝突しません。古い索引は自動では消えないので、容量を戻したいときはlumen cleanを使います。

lumen clean            # 30日使われていない索引、またはプロジェクトが消えた索引を削除
lumen clean --days 7   # 基準を1週間に狭める
lumen clean --days 0   # 実行中の索引を除き、削除できる索引をすべて消す

索引は開くたび(検索・索引化・状態確認・セッション開始)に「使われた」と数えられるため、日常的に触っているプロジェクトの索引は消えません。

何が索引されるか

索引に入るファイルは、複数の層を順に通ったものだけです。

1. 組み込みの除外(node_modules、vendor、dist、.venv、target、.next、testdataなどのディレクトリと、package-lock.jsonやCargo.lockなどのロックファイル)
2. .gitignore
3. .lumenignore
4. .gitattributesのlinguist-generated指定
5. 対応する拡張子

.lumenignoreは.gitignoreと同じ書式で、プロジェクトのルートかサブディレクトリに置きます。.gitignoreには載っていないが検索のノイズになるファイル、たとえば生成されたprotobuf、テストのスナップショット、同梱された外部データを外すために使います。

# .lumenignore の例(.gitignoreと同じ書式)
*.pb.go
**/__snapshots__/
third_party/data/

上の3行は書式を示す例で、READMEにある設定そのものではありません。

設定は環境変数で行う

設定はすべて環境変数です。

LUMEN_EMBED_MODELの既定値はバックエンドごとに違い、LM Studioではnomic-ai/nomic-embed-code-GGUFになります。

モデルの選び方

READMEは、登録済みモデルに推奨度を付けています。

nomic-embed-text、qwen3-embedding:0.6b、all-minilmは「Untested」です。推奨度の高い既定モデルから試し、Untestedのモデルは動作や効果の裏づけがないため比較の対象外と考えるのが無難です。

登録されていないモデルを使うときは、LUMEN_EMBED_DIMSを必ず指定します。READMEの例は次のとおりです。

LUMEN_BACKEND=lmstudio
LM_STUDIO_HOST=http://localhost:8801
LUMEN_EMBED_MODEL=mlx-community/Qwen3-Embedding-8B-4bit-DWQ
LUMEN_EMBED_DIMS=4096
LUMEN_EMBED_CTX=40960   # 省略可。既定は8192

複数のサーバーをconfig.yamlに定義している場合、lumen indexとlumen searchは--model/-mと--backend/-bで使うサーバーを選べます。同じモデル名を2つのバックエンドに設定すると索引が共有されてしまう点がREADMEに注意として書かれており、バックエンドごとにモデル名を分ける必要があります。

公開ベンチマークをどう読むか

READMEのベンチマークは、実在のGitHub issueを使ったSWE-bench形式の課題で、Lumenあり・なしを比べたものです。測っているのはコスト、時間、出力トークン、パッチの質で、生のJSONLやパッチの差分、判定の根拠もリポジトリに置かれているとされています。

9言語・難度「hard」の結果は、次のとおりです(埋め込みモデルは既定のOllama構成)。

読むときの注意点は3つです。

1. コストの削減幅は言語によって8%から39%まで開いています。「30%減る」は平均的な見込みではなく、リポジトリの説明文にある宣伝上の数字です。
2. 列は「出力トークン」で、入力側のトークンではありません。減るのは主にClaudeが生成する量とコストです。
3. C++は出力トークンが42%増えています。READMEはこれを機能追加の課題だったためとしています。

READMEは「質はすべての課題で維持され、退行はゼロ」と述べています。RustとSvelteは、Lumenあり・なしのどちらでも課題が難しすぎて質が低かった例で、そこでも失敗のコストは26〜39%下がったとされています。これは提供元が自分で用意した課題での結果です。自分のリポジトリで同じ傾向になるかは、少数の質問で前後を比べて確かめるのが確実です。

プラグインがセッションに常駐させる固定のコンテキスト量は、claude plugin detailsの記事の手順で測れます。検索で減る量と、プラグイン自体が足す量を並べて見ると、手元での損得が分かります。

つまずいたときの切り分け

READMEのトラブルシューティングから、実際に起きそうなものを選びます。

LM Studioを使う場合には、固有の落とし穴もあります。LM Studioは埋め込みモデルをGGUFのarchフィールドの許可リスト(bert、nomic-bert)で分類するため、nomic-embed-codeのようなQwen2系のモデルは「Embeddings」でなく「LLMs」に分類されます。GGUFでv0.3.16以降なら、My Modelsの歯車アイコンから「Override Domain Type」を「Text Embedding」にして直せます。Apple SiliconではMLX形式が大幅に速い一方、LM Studioはv0.3.30以降でMLXのドメイン種別の上書きを削除しました。そのためGGUF版を使うか、Ollama側のモデルに切り替えるのが回避策です。

入れる前の判断材料

Lumenは「コードを意味で引く」道具なので、効き方には向き不向きがあります。公式のページとREADMEから言える範囲を表にします。

Dart(コスト-76%、トークン-82%、時間-79%)の数字は、言語の表には載っていますが、上の9言語の表には入っていません。同じREADME内でも集計の範囲が表ごとに違うため、数字は表の見出しとセットで読む必要があります。

同じマーケットプレイスでも、差分を外部サービスに送ってレビューを受けるQodoプラグインは、データを手元に残すLumenとは対照的です。

まとめ

Lumenが減らしたいのは、答えにたどり着くまでの探索コストです。導入は2コマンド、前提はOllamaと埋め込みモデルのpull、確認は/lumen:doctorで足ります。

数字を使うときは、提供元の「30%」を目標値と受け取らず、言語ごとに8%から39%まで幅がある公開結果として読みます。自分のリポジトリでは、同じ質問を入れる前と入れた後で投げ、トークンの内訳を見比べるのが確実です。索引は~/.local/share/lumen/にあるので、試して合わなければプラグインを外し、lumen clean --days 0で容量も戻せます。