ripsem

ripsem

これを実行しているコードはどこにありますか？

はじめる · 使い方 · コーディングエージェント · 仕組み · トラブルシューティング

ripsemは、人とコーディングエージェントのための、ローカルでオフライン動作するコード検索ツールです。 識別子、エラーメッセージ、または動作の平易な説明を使って検索すると、該当する関数や型が名前と行範囲とともに、順位付けされて返されます。

• あらゆる形式の質問を1回のクエリで検索。 コードを考慮したトークンによるBM25と、ローカル埋め込みモデルによるベクトル類似度を組み合わせ、1つの順位にまとめます。識別子やエラーメッセージのすべての語句を含むチャンクが先頭に表示されます。
• 回答は宣言です。 検索結果は、17言語に対応した、名前が付いた関数または型全体です。定義を呼び出し箇所と区別して読み取れます。名前で検索すれば、その名前を持つ宣言が行範囲とラベル付きで見つかります。
• コーディングエージェント向けに設計。 ripsem install claude-code、cursor、vscode、geminiを実行すると、エージェントの編集に合わせてインデックスを最新に保つMCP サーバーが追加され、エージェントに使用すべきタイミングも伝えます。
• オフライン。 アカウントもAPIキーもサービスも必要ありません。モデルは一度ダウンロードすればCPU上で動作し、インデックスはリポジトリ内の1つのファイルに保存されます。

はじめる

1. ripsemをインストールします。

   npm（すべてのプラットフォーム）：

   npm install -g ripsem
   

   Cargo：

   cargo install --locked ripsem
   

   npmまたはRustを使わずにmacOSとLinuxでインストールする場合：

   curl -fsSL https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.sh | sh
   

   npmまたはRustを使わずにWindowsでインストールする場合：

   irm https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.ps1 | iex
   

2. リポジトリ内で、調べたいことを質問します。

   ripsem search "strip the auth header when redirecting to another host"
   

3. ripsem install claude-code、ripsem install cursor、ripsem install vscode、またはripsem install geminiを実行して、同じ検索をコーディングエージェントに任せます（下記を参照）。

Gitリポジトリ、またはripsem initを実行済みのディレクトリで初めて検索すると、インデックスが構築されます。モデル（約133 MB）を一度ダウンロードし、リポジトリを埋め込みます。2回目以降の検索では、前回から変更された内容だけを埋め込むため、結果が移動後のコードを指すことはありません。Windowsでは、GPUがある場合、初回のインデックス作成時にDirectMLを使ってGPU上で処理します。

grepではなくripsemを使う理由

grepが答えるのは「この文字列はどこにあるか」です。文字列がわかっている場合は、それが適切な質問です。ripsemは、コードの動作はわかっていても、その名前がわからないときに使います。説明から関数を見つけられ、識別子やエラーメッセージでも、字句検索が文字列をそのまま認識するため、完全一致を見つけられます。検索結果は一致した行ではなく、名前付きの関数または型全体です。そのため、ファイルを開かなくても、読み手やエージェントは定義と呼び出し箇所を区別できます。

インストール

npm とインストールスクリプトは、最新の リリースからビルド済みバイナリを取得し、リリースの SHA256SUMSと照合してからPATHに追加します。インストール先は ~/.local/binと%LOCALAPPDATA%\Programs\ripsemです。RIPSEM_INSTALL_DIR を指定すると、インストール先を変更できます。リリースアーカイブを手動で展開することもできます。Windowsでは、 DirectML.dllをripsem.exeと同じ場所に置いてください。

プラットフォーム	動作環境
x86_64-unknown-linux-gnu	glibc 2.35、libstdc++ 12、OpenSSL 3 以降：Ubuntu 22.04、Debian 12 以降
aarch64-unknown-linux-gnu	64 ビット Arm 上の glibc 2.39、libstdc++ 14、OpenSSL 3 以降：Ubuntu 24.04、Debian 13 以降。AWS Graviton など。npm からはまだインストールできず、インストールスクリプトまたはアーカイブを使用してください
aarch64-apple-darwin	Apple シリコン搭載の macOS 13.4 以降
x86_64-pc-windows-msvc	Microsoft Visual C++ Redistributableを備えた Windows 10 以降

x86-64 ビルドの埋め込みランタイムには、AVX2 対応の CPU（Intel Haswell、AMD Excavator 以降）が必要です。バイナリには埋め込みランタイムと tree-sitter が含まれます。モデルは初回使用時にダウンロードされます。

cargo installでは、Rust 1.92 以降を使ってソースからビルドします。ビルドではビルド済みの ONNX Runtime がダウンロードされ、C および C++ コンパイラーに加え、Linux では pkg-config と OpenSSL のヘッダーが必要です（Debian および Ubuntu ではbuild-essential pkg-config libssl-dev）。

タグ付きリリースが安定版で、npm、Cargo、インストールスクリプトはいずれも最新の安定版をインストールします。masterには次回リリース向けの変更が含まれ、CHANGELOG.mdの「Unreleased」に記載されています。

チェックアウトから最新リリースをビルドするには、次を実行します。

git clone https://github.com/Sadykhzadeh/ripsem
cd ripsem
git checkout "$(git describe --tags --abbrev=0)"
cargo install --locked --path .

git checkoutを省略すると、masterがビルドされます。

デフォルトで有効なfastembed機能は、ローカルの埋め込みランタイムを組み込みます。--no-default-featuresを指定してビルドすると、ripsem は意味ではなく単語を照合する軽量なハッシュバックエンドで動作します。テストスイートではこのバックエンドを使用します。

デフォルトで有効なtreesitter機能は、固定行数のウィンドウではなく関数や型の境界でコードを分割し、各チャンクに属する宣言の名前を付けます。結果はsrc/auth/session.rs:40-72 fn Session::refreshのようになり、ファイルを開かなくても、定義と呼び出し箇所を見分けられます。1 つのチャンクに収まらない大きさの関数では、分割された各チャンクにその名前が付けられます。Rust、Python、JavaScript、TypeScript、Go、Java、C、C++、C#、 Ruby、PHP、Scala、Kotlin、Bash、HTML、CSS、JSON に対応しています。それ以外のファイルは行数で分割されます。

hnsw機能は、チャンク数が 500 000 を超えるインデックス向けに、近似最近傍グラフを追加します。変更されるのはベクトル側で候補を集める方法だけです。字句側とマージの動作は、どのサイズでも変わりません。

シェル補完

ripsem completions bash > ~/.local/share/bash-completion/completions/ripsem
ripsem completions zsh > ~/.zfunc/_ripsem
ripsem completions fish > ~/.config/fish/completions/ripsem.fish
ripsem completions powershell >> $PROFILE

使用方法

ripsem init                       # write .ripsem/config.toml
ripsem index                      # build the index (incremental on re-runs)
ripsem search "where is auth set up?"   # updates the index first
ripsem status                     # index size, counts, model, drift from the tree
ripsem status --json              # the same as JSON (schema ripsem/status/v1)
ripsem watch                      # keep the index in sync as files change

git と同様に、init 以外のすべてのコマンドは、どのサブディレクトリからでも実行できます。.ripsem ディレクトリを含む最も近い親ディレクトリを使用します。--path <dir> でこれを上書きできます。

インデックスは git の対象外です。.ripsem/.gitignore にインデックスが記載されているため、git status にはコミット可能な config.toml と .gitignore だけが表示されます。ripsem は .gitignore が存在しない場合に作成しますが、既存のファイルは変更しません。

status は、インデックスとファイルの差異の程度も報告します。検索結果には、インデックス作成時点でのファイルの行範囲が付与されるため、tree: out of date: 3 changed, 1 new と表示された場合、結果が現在は正しい行を指していない可能性があるとわかります。差異は、増分インデックスで使われるものと同じコンテンツハッシュで測定されるため、再構築で処理される内容が正確にカウントされます。JSON では index.drift（added／modified／removed）として含まれます。

結果は、統合されたランキング順に、path:start-end、宣言名、スニペットを表示します。上位 3 件には最大 40 行のコードが含まれるため、ファイルを開かずに回答を確認できます。同じ行範囲を含むレコード（宣言とその上のドキュメント、または隣接するウィンドウ）は一度だけ返されるため、-k 5 は異なる 5 か所を意味します。表示される数値は 0 から 1 までで、リポジトリ内の無関係なテキストよりもその結果の意味がどれほど際立っているか、またはクエリの語句が文字どおり含まれる割合のうち、高い方を表します。リストの下に行くほど数値が高くなることはないため、しきい値を設定するとランキング上位が残ります。各インデックスは、コード以外のあらゆるものについてのクエリを照合し、独自のノイズフロアを測定します。そのため、尺度はリポジトリとモデルに応じたものになります。

クエリの語句を引用符で囲む必要はありません。ripsem search where is auth set up は ripsem search "where is auth set up" と同じ検索を行います。

• -k <N> は検索結果の数を設定します（デフォルトは 10）。
• --json は検索結果を JSON 配列として出力します。各項目には path、start_line、end_line、score、kind、symbol（fn や Session::refresh など。宣言外の結果ではどちらも null）および snippet が含まれます。--count-by-file を指定すると、各項目は path と count になります。
• --in <subdir> は検索結果をサブディレクトリ内に限定します。相対パスはシェルと同様に現在のディレクトリを起点とします。src 内では、--in auth は src/auth を、--in . は src を意味します。リポジトリ内の絶対パスも使用できます。
• --context <N> は、検索結果ごとに表示するスニペットの行数を設定します（ターミナルでは 3 行、出力が別のプログラムに渡される場合はスニペット全体を表示します。0 を指定すると場所だけを表示します）。
• --min-score <SCORE> は、人間向け出力と JSON 出力の両方で、強い一致だけを残します。
• --count-by-file は検索結果の代わりにファイルごとの一致件数を出力します。

モデル

ripsem model list                 # show available models
ripsem model set bge-base-en-v1.5
ripsem index                      # rebuilds the index for the new model

モデル	次元数	ディスク容量	備考
bge-small-en-v1.5	384	約133 MB	デフォルト
all-MiniLM-L6-v2	384	約90 MB	埋め込みの作成が最小かつ最速
bge-base-en-v1.5	768	約436 MB	より大きな英語モデル
multilingual-e5-small	384	約470 MB	他の言語でのクエリとコメントに対応
nomic-embed-text-v1.5	768	約550 MB	より大きな英語モデル。インデックス作成時のメモリ使用量が最大

モデルは初回使用時に一度ダウンロードされ、その後はすべてオフラインで動作します。

コーディングエージェントでの使用

ripsem install claude-code        # .mcp.json and a note in CLAUDE.md
ripsem install cursor             # .cursor/mcp.json and a rule in .cursor/rules
ripsem install vscode             # .vscode/mcp.json and .github/copilot-instructions.md
ripsem install gemini             # .gemini/settings.json and a note in GEMINI.md

install はサーバーを登録し、.ripsem/config.toml を書き込み、grep の前に search を使うようエージェントに伝える短いメモを追加します。そのディレクトリでエージェントを再起動すると、search を直接呼び出せます。

サーバーは同じメモを MCP の指示として送信します。Claude Code はモデルが MCP ツールを検索したときにのみその説明を読み込むため、モデルは search の存在と使用するタイミングを、指示と CLAUDE.md のメモから学びます。

ripsem mcp は stdio 経由で MCP を話し、単一の search ツールを公開します。引数は query と、任意で検索範囲を絞る path、limit（既定値は 5、最大 50）、および min_score です。スキーマにない引数を指定すると、期待される内容を示すツールエラーが返されるため、エージェントは呼び出しを修正できます。.ripsem ディレクトリがあるディレクトリでは、サーバーがインデックスを自動的に最新の状態に保ちます。初回起動時にインデックスを作成し、エージェントが変更したコードを再度埋め込みます。事前に ripsem index を一度実行しておくと、最初の検索前にインデックスを準備できます。

ほかの MCP クライアントでは、それぞれの設定に同じエントリを追加します。

{
  "mcpServers": {
    "ripsem": { "command": "ripsem", "args": ["mcp"] }
  }
}

ripsem がインストールされていない場合、クライアントは "command": "npx", "args": ["-y", "ripsem", "mcp"] を使って起動できます。

サーバーは起動元のディレクトリからインデックスを見つけます。別の場所にあるリポジトリを指定するには、args に "--path", "/path/to/repo" を追加します。install cursor と install vscode は "--path", "${workspaceFolder}" を書き込み、エディターがこれをプロジェクトのパスに展開します。VS Code では、サーバーは mcpServers ではなく servers の下に一覧表示されます。ホームディレクトリからサーバーを起動する場合など、ワークスペースのルートを共有するクライアントでは、プロジェクト自体を指定してください。--path はワークスペースのルートより優先されます。

設定

.ripsem/config.toml：

backend = "fastembed"
model = "bge-small-en-v1.5"
chunk_lines = 40
chunk_overlap = 8
max_chunk_lines = 50
max_file_kb = 1024
skip_generated = true
exclude = []

chunk_lines と chunk_overlap は、プレーンテキストファイルやパーサーのない言語で使用する行ウィンドウのサイズを指定します。max_chunk_lines は単一のセマンティックチャンクの上限を設定し、これを超える大きな関数は分割されます。この3つのいずれかを変更すると、次回の ripsem index ですべてのファイルが再度チャンク化され、埋め込まれます。max_file_kb より大きなファイルはスキップされます。exclude には、.gitignore と任意の .ripsemignore に加えて、gitignore 形式のグロブを指定します。backend = "hash" は意味ではなく単語を照合します。fastembed 機能なしでビルドした場合は、このバックエンドで起動します。ripsem が認識しないキーを指定すると、エラーとして報告されます。

skip_generated を有効にすると、コミット済みでも機械によって生成されたファイル（ロックファイル、go.sum、*.min.js、*.min.css、ソースマップ）が除外されます。これらは意図的にコミットされているため、.gitignore では対象になりません。また、ロックファイル1つが手書きのファイルすべてより大きくなることもあります。それでもインデックス化するには、false に設定します。

仕組み

1. 走査。 git が認識する方法でツリーを読み込みます。.gitignore、グローバルの gitignore、.ripsemignore が適用され、バイナリファイル、max_file_kb を超える ファイル、機械生成ファイルは対象外になります。
2. チャンク分割。 tree-sitter が関数と型の境界で各ファイルを分割し、各チャンクに 宣言名を付けます。ドキュメントコメントや docstring は同じ宣言の 2 つ目の レコードになります。これは、作成者がコード自体ではほとんど使われない言葉で コードを説明するためです。
3. 埋め込みとトークン化。 各チャンクはローカルモデルからベクトルを取得し、 int8 として保存されます。また、識別子をそのまま保持しつつ、snake_case と camelCase の境界でも分割した用語セットを作成します。各チャンクには、含まれる 宣言とその行番号も記録されます。
4. 検索。 クエリを両方の検索経路に通し、逆順位融合でランキングを統合します。 クエリの情報量のある用語をすべて含むチャンクが最初に表示されるため、識別子や エラーメッセージを確実に検索できます。コードとして入力された場合も、言葉で 書かれた場合も、宣言名を指定したクエリでは、その宣言を使用するだけのチャンク より、宣言を含むチャンクが上位に表示され、その宣言が報告されます。その下では、 テストを求めるクエリでない限り、コードがテストより上位に、そのコードを説明する prose よりも上位に表示されます。
5. 最新状態の維持。 インデックスは .ripsem/index.bin という 1 つのファイルです。 再実行すると、内容が変更されたファイルだけを読み込み、テキストが変更された チャンクだけを埋め込みます。モデルまたはチャンク設定を変更すると、再構築されます。 ripsem watch はファイルの変更に応じてインデックスを最新状態に保ち、MCP サーバーは 再起動せずに再構築されたインデックスを読み込みます。

トラブルシューティング

ファイルが検索結果に一度も表示されません。 ripsem index --dry-run を実行すると、 インデックスに含まれるすべてのファイルが表示されます。.gitignore、 .ripsemignore、または exclude に一致するファイル、バイナリファイル、 max_file_kb より大きいファイル、あるいは skip_generated によって機械生成と 判定されたファイルは対象外になります。

検索結果の行番号が正しくありません。 インデックス作成後にファイルが変更されています。 ripsem search は検索前にインデックスを更新し、ripsem watch または実行中の MCP サーバーは インデックスを最新状態に保ちます。ripsem status でずれの程度を確認できます。

インデックスの作成に別のモデルが使われたと表示されます。 設定で、インデックスとは 異なるモデルまたはバックエンドが指定されています。ripsem index は設定に合わせて インデックスを再構築します。

エージェントが search を呼び出しません。 サーバーはエージェントとともに起動するため、 install の後にリポジトリ内でエージェントを再起動してください。Claude Code では、 /mcp に接続済みのサーバーが一覧表示されます。

最初のインデックス作成に時間がかかります。 モデルは一度だけダウンロードされ、すべての ファイルが埋め込まれます。埋め込み済みのチャンク数と残り時間の推定値が表示されます。 以降の実行では、変更されたコードだけが埋め込まれます。Windows では 256 個以上のチャンクを 処理するジョブは DirectML 経由で GPU 上で実行され、CPU より約 4 倍速くなります。 たとえばグラフィックスドライバーに問題がある場合は、RIPSEM_NO_GPU=1 を設定すると CPU で実行されます。モデルは Linux では ~/.cache/ripsem、macOS では ~/Library/Caches/ripsem、Windows では %LOCALAPPDATA%\ripsem\cache に キャッシュされます。RIPSEM_MODEL_DIR で別のディレクトリを指定できます。

Windows で ripsem.exe が起動しません。 VCRUNTIME140.dll または MSVCP140.dll が見つからない場合、Microsoft Visual C++ Redistributable が インストールされていません。winget install Microsoft.VCRedist.2015+.x64 を実行して インストールできます。DirectML.dll が見つからない場合は、アーカイブを展開した際に ripsem.exe の隣に配置されませんでした。

品質

ランキングの評価では、4 言語（Rust、Python、Go、TypeScript）で書かれ、それぞれリリースタグに固定された4つの実プロジェクトを対象とする、ラベル付きの質問のベンチマークを使用します。質問は、実際に検索で使われる4種類の形式です。自分の言葉で書いた説明、識別子、出力に表示されたメッセージ、そして誤って覚えている名前です。統合後のランキングは、どちらか一方の検索手法を単独で使う場合を上回り、質問の少なくとも86%で回答を上位5件に含める必要があります。また、回答が含まれるファイルを読む場合より、回答にたどり着くまでに読む量が少なくなければなりません。2つ目のテストでは、これらのプロジェクトで一度ずつ宣言されているすべての名前を検索します。少なくとも95%で、最初の検索結果がその宣言であり、宣言自体の名前が使われている必要があります。また、宣言行への検索結果に別の名前が付いていてはなりません。

cargo test --release --test retrieval_quality -- --ignored --nocapture \
  fusion_beats_either_retriever_alone a_declared_name_leads_to_its_declaration

初回の実行では、4つのプロジェクトを target/corpora にクローンし、モデルをダウンロードします。ランキングの変更をどのように評価するかについては、CONTRIBUTING.md を参照してください。

ライセンス

Apache-2.0