semble

semble — エージェント向けの高速かつトークン効率に優れたコード検索

grep+read と比べてトークンを約98％削減します。約250msでインデックスを作成し、約1.5msでクエリに応答します。GPUもAPIキーも不要です。

Semble は、ファイル全体を grep したりディレクトリを読み込んだりせず、エージェントが必要とする関連コードスニペットだけを返します。"authentication flow" や "save_pretrained" のような自然言語またはシンボルのクエリを入力すると、ファイルパスと行範囲を含む正確なチャンクだけが返されます。

インストール

MCP（Claude Code — 推奨）

# Requires uv: https://docs.astral.sh/uv/getting-started/installation/
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

MCP（Codex）

~/.codex/config.toml に追加します：

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

MCP（Cursor）

~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

MCP（OpenCode）

~/.opencode/config.json に追加します：

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

CLI / pip

pip install semble        # pip
uv tool install semble    # uv (recommended for CLI use)

スキル（任意のプラットフォーム）

npx skills add https://github.com/akillness/jeo-skills --skill semble

使用する場面

• 自然言語で動作を説明してコードベースを検索する（"how is rate limiting handled"）
• 正確なファイルがわからない場合に、シンボルや識別子を検索する（"save_pretrained"）
• 既知の場所と意味的に類似したコードを見つける（find-related）
• MCP 経由で任意のリポジトリにトークン効率よくアクセスできるようエージェントに提供し、ファイル全体を grep したり読み込んだりさせない
• 事前にクローンせずにリモート git リポジトリのインデックスを作成する

使用しない場面

• ファイル全体またはディレクトリ一覧を読む必要がある場合 → ネイティブの Read、Glob ツールを使用します
• 正規表現または完全一致の文字列検索が必要な場合 → Grep のほうが適しています
• インデックスを作成するほど大きくないリポジトリ（数ファイル程度）の場合 — 直接読み込みます
• テストの実行、ビルド、コードの実行が必要な場合 — これは検索専用ツールです

CLI の使用方法

# Natural-language search in a local repo
semble search "authentication flow" ./my-project

# Symbol search
semble search "save_pretrained" ./my-project

# Search with a limit on returned chunks
semble search "save model to disk" ./my-project --top-k 10

# Search a remote git repo (no clone needed)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# Find semantically similar code given a known file+line
semble find-related src/auth.py 42 ./my-project

# Show token savings vs grep+read for the last query
semble savings
semble savings --verbose

Python ライブラリ

from semble import SembleIndex

# Index local directory
index = SembleIndex.from_path("./my-project")

# Index remote repository (no clone required)
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Natural-language or symbol query
results = index.search("save model to disk", top_k=3)

# Find semantically similar code to a known chunk
related = index.find_related(results[0], top_k=3)

# Inspect results
result = results[0]
print(result.chunk.file_path)   # "model2vec/model.py"
print(result.chunk.start_line)  # 127
print(result.chunk.end_line)    # 150
print(result.chunk.content)     # the function/class body

AGENTS.md / CLAUDE.md との連携

プロジェクトの AGENTS.md または CLAUDE.md に次のセクションを追加すると、すべてのエージェントで semble を有効にできます：

## Code Search

Use `semble search` to find code by describing what it does or naming a symbol, instead of grep:

​```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10
​```

Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):

​```bash
semble find-related src/auth.py 42 ./my-project
​```

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.

Claude Code のサブエージェントでは、プロジェクトのルートで一度だけ初期化します：

semble init

パフォーマンスベンチマーク

指標	Semble	grep+read
インデックス作成速度	~250ms	n/a
クエリ速度	~1.5ms	varies
再現率94％でのトークン使用量	~2k tokens	~100k tokens
NDCG@10	0.854	—
1億3700万パラメーターの CodeRankEmbed との比較	品質99％	—
Transformer と比べたインデックス作成速度	218× faster	—

運用ルール

1. 対話型エージェントでの使用には MCP によるインストールを優先し、スクリプトや CI では CLI/pip を優先します。
2. --top-k を使って結果を制限し、コンテキストを小さく保ちます — デフォルト値はエージェントのプロンプトには大きすぎることがよくあります。
3. 既知のチャンクから類似コードへ検索を広げる必要がある場合は、search の後に find-related を使用します。
4. Claude Code のサブエージェント向けにインデックスを事前にウォームアップするには、プロジェクトのルートで semble init を使用します。
5. $PATH に semble がない場合は、スクリプト内で uvx --from "semble[mcp]" semble に置き換えます。
6. Semble は最初の検索手段として使用し、返されたチャンクだけではコンテキストが不十分な場合に限り、ファイル全体を読みます。

例

# Search for how a feature is implemented
semble search "rate limiting middleware" ./api-service

# Find all code related to database migrations
semble search "database migration" ./backend --top-k 5

# Explore similar code patterns near a known function
semble find-related src/middleware/auth.py 88 ./api-service

# Index and query a remote library without cloning
semble search "tokenizer padding" https://github.com/huggingface/transformers

出典：MinishLab/semble — MIT ライセンス