osgrep-reference

osgrep：セマンティックコード検索

概念的なコード探索には、grep/rg より osgrep を優先してください。文字列の一致だけでなく、意味に基づいてコードを見つけます。識別子やリテラル文字列を正確に検索する場合は、引き続き grep/rg が適しています。

概要

osgrep は、キーワードの一致ではなく概念に基づいてコードを見つける、自然言語によるセマンティックコード検索ツールです。リテラル文字列に一致する grep とは異なり、osgrep はローカルの AI 埋め込みを使用してコードの意味を理解します。

バージョン 0.5.16（2025 年 12 月）の主な更新：

• skeleton コマンド：ファイルを関数／クラスのシグネチャに圧縮します（トークンを約 85% 削減）
• trace コマンド：任意のシンボルについて、呼び出し元／呼び出し先を表示します（呼び出しグラフ）
• symbols コマンド：インデックス化されたすべてのシンボルと定義を一覧表示します
• doctor コマンド：健全性／整合性を検証します
• list コマンド：インデックス化されたすべてのリポジトリを表示します
• プロジェクトごとの .osgrep/ ディレクトリ（グローバルな ~/.osgrep/data は不要になりました）
• パフォーマンスを改善した V2 アーキテクチャ（トークンを約 20% 節約し、速度を約 30% 向上）
• Go 言語に対応
• インデックスをクリーンに再作成する --reset フラグ
• 関連性の高い結果を得るための ColBERT 再ランキング
• 役割の検出：オーケストレーションロジックと型定義を区別します
• 検索の分割：「コード」と「ドキュメント」のインデックスを分離します

osgrep を使用する場面：

• 不慣れなコードベースを探索する場合（「認証ロジックはどこにありますか？」）
• 概念的なパターンを見つける場合（「エラー処理を表示してください」）
• 横断的な関心事を特定する場合（「すべてのデータベースマイグレーション」）
• ユーザーがセマンティックコード検索を明示的に求めている場合

従来のツールを使用する場面：

• 正確な文字列や識別子を検索する場合（Grep を使用）
• ファイル名のパターンでファイルを見つける場合（Glob を使用）
• 正確な場所がすでに分かっている場合（Read を使用）

クイックスタート

プロジェクトごとの .osgrep/ インデックスを使用するため、プロジェクトディレクトリ内から osgrep を実行してください。

cd /path/to/project      # REQUIRED: cd into the project first
osgrep "your query"      # Now search works

基本的な検索

osgrep "your semantic query"
osgrep search "your query" path/to/scope    # Scope to subdirectory
osgrep skeleton src/file.py                 # Compress file to signatures
osgrep trace functionName                   # Show call graph
osgrep symbols                              # List all symbols

例：

osgrep "user registration flow"
osgrep "webhook signature validation"
osgrep "database transaction handling"
osgrep "how are plugins loaded" packages/src

出力形式

次の形式で結果を返します：

IMPLEMENTATION path/to/file:line
Score: 0.95

Preamble:
[code snippet or content preview]
...

• IMPLEMENTATION：一致の種類を示すタグ
• Score：関連性スコア（0～1。値が大きいほど適切です）
• ...：切り捨てを示すマーカー。スニペットは不完全なため、全体を確認するには Read を使用してください

検索戦略

アーキテクチャ／システムレベルの質問の場合

用途：認証、統合、ファイル監視、横断的な関心事

1. まず幅広く検索して全体像を把握します：

   osgrep "authentication authorization checks"
   

2. 結果を調べます - 複数のファイルに共通するパターンを探します：

   • チェックはミドルウェアにありますか？デコレーターですか？複数のサービスにありますか？
   • ファイルパスから異なるレイヤー（ゲートウェイ、ハンドラー、ユーティリティ）が示されていますか？

3. 戦略的に読みます - 異なる側面を表すファイルを 2～4 個選びます：

   • メインのエントリーポイントを読みます
   • 代表的なミドルウェア／ユーティリティのファイルを読みます
   • アーキテクチャが不明確な場合は、インポートをたどります

4. ある側面が不明確な場合は、具体的な検索で絞り込みます：

   osgrep "session validation logic"
   osgrep "API authentication middleware"
   

実装の詳細を絞り込んで調べる場合

用途：特定の関数、アルゴリズム、単一の機能

1. 正確なロジックを具体的に検索します：

   osgrep "logic for merging user and default configuration"
   

2. 意味的な一致を評価します：

   • スニペットは関連性がありそうですか？
   • ... で終わっている場合や、ロジックの途中で切れている場合は、ファイルを読んでください

3. 検索 1 回、読み取り 1 回：osgrep で最適なファイルを特定し、その後、ファイル全体を読みます。

CLI リファレンス

検索オプション

結果数を制御する：

osgrep "validation logic" -m 20           # Max 20 results total (default: 10)
osgrep "validation logic" --per-file 3    # Up to 3 matches per file (default: 1)

出力形式：

osgrep "API endpoints" --compact           # File paths only
osgrep "API endpoints" --content           # Full chunk content (not just snippets)
osgrep "API endpoints" --scores            # Show relevance scores
osgrep "API endpoints" --plain             # Disable ANSI colors

検索前に同期する：

osgrep "validation logic" -s               # Sync files to index before searching
osgrep "validation logic" -d               # Dry run (show what would sync)

インデックス管理

osgrep index                    # Incremental update
osgrep index -r                 # Full re-index from scratch (--reset)
osgrep index -p /path/to/repo   # Index a specific directory
osgrep index -d                 # Preview what would be indexed (--dry-run)

高度なコマンド（v0.5 以降）

Skeleton - ファイルをシグネチャに圧縮：

osgrep skeleton src/server.py              # Show function/class signatures only
osgrep skeleton src/server.py --no-summary # Omit call/complexity summaries
osgrep skeleton "auth logic" -l 5          # Query mode: skeleton of top 5 matching files

出力には、関数シグネチャと、本文内の # → calls | C:N | ORCH 形式の要約が表示されます。

Trace - 呼び出しグラフを表示：

osgrep trace handleRequest                 # Who calls this? What does it call?

Symbols - インデックス化されたすべてのシンボルを一覧表示：

osgrep symbols                             # All symbols (default limit: 20)
osgrep symbols "Request"                   # Filter by pattern
osgrep symbols -p src/api/ -l 50           # Filter by path, increase limit

その他のコマンド

osgrep list                     # Show all indexed repositories
osgrep doctor                   # Check health and configuration
osgrep setup                    # Pre-download models (~150MB)
osgrep serve                    # Run background daemon (port 4444)
osgrep serve -p 8080            # Custom port (or OSGREP_PORT=8080)
osgrep serve -b                 # Run in background (--background)
osgrep serve status             # Check if daemon is running
osgrep serve stop               # Stop daemon
osgrep serve stop --all         # Stop all daemons

エンドポイントを提供する：

• GET /health - ヘルスチェック
• POST /search - { query, limit, path, rerank } を使った検索
• ロックファイル：port／pid を含む .osgrep/server.json

Claude Code との統合

osgrep install-claude-code      # Install as Claude Code plugin
osgrep install-opencode         # Install for Opencode

どちらのプラグインも、セッション中にバックグラウンドサーバーのライフサイクルを自動的に管理します。

よく使われる検索パターン

アーキテクチャの探索

# Mental processes (Open Souls / Daimonic)
osgrep "mental processes that orchestrate conversation flow"
osgrep "subprocesses that learn about the user"
osgrep "cognitive steps using structured output"

# React/Next.js
osgrep "where do we fetch data in components?"
osgrep "custom hooks for API calls"
osgrep "protected route implementation"

# Backend
osgrep "request validation middleware"
osgrep "authentication flow"
osgrep "rate limiting logic"

ビジネスロジック

osgrep "payment processing"
osgrep "notification sending"
osgrep "user permission checks"
osgrep "order fulfillment workflow"

横断的な懸念事項

osgrep "error handling patterns"
osgrep "logging configuration"
osgrep "database migrations"
osgrep "environment variable usage"

効果的なクエリのヒント

意味を重視する

正確な名前を指定する必要はありません。概念的なクエリのほうが効果的です。

# Good - conceptual
osgrep "how does the server start"
osgrep "component state management"

# Less effective - too literal
osgrep "server.init"
osgrep "useState"

具体的にする

# Too vague
osgrep "code"

# Clear intent
osgrep "user registration validation logic"

自然言語を使う

osgrep "how do we handle payment failures?"
osgrep "what happens when a webhook arrives?"
osgrep "where is user input sanitized?"

分散パターンに注意する

異なるディレクトリにある5個以上のファイルに結果がまたがる場合、その機能はアーキテクチャに関わる可能性が高いため、深く調べる前に全体を確認してください。

スニペットに頼りすぎない

アーキテクチャに関する質問では、スニペットは手がかりであり、答えではありません。重要なファイルを読んでください。

技術的な詳細

• 100%ローカル：transformers.js の埋め込みを使用します（リモート API 呼び出しはありません）
• 自動分離：各リポジトリは独自のインデックスを .osgrep/ ディレクトリに持ちます（v0.5+）
• 適応型パフォーマンス：同時実行数の上限により、システムの応答性を維持します
• インデックスの場所：プロジェクトのルートにある .osgrep/（v0.4.x では ~/.osgrep/data/）
• モデルのダウンロード：初回実行時に約150MB（事前にダウンロードするには osgrep setup を実行）
• チャンク分割戦略：Tree-sitter がコードを関数／クラスの境界に分割します
• 重複排除：同一のコードブロックは重複排除されます
• デュアルチャネル：ColBERT による再ランク付けを備えた「Code」と「Docs」の個別インデックス
• 構造的な優先付け：テストファイルより関数／クラスを優先します
• スケルトン圧縮：ファイル構造を表示する際にトークンを約85%削減します

トラブルシューティング

「Still Indexing...」メッセージ：

• インデックス作成中です。完了するまでは結果が不完全になります。
• ユーザーに知らせ、続行するかどうかを尋ねてください。

初回検索が遅い：

• 想定どおりです。中規模のリポジトリでは、インデックス作成に30～60秒かかります
• モデルを事前にダウンロードするには osgrep setup を使用してください

インデックスが古い：

• 更新するには osgrep index を実行します
• インデックスを完全に作り直すには osgrep index --reset を実行します
• osgrep は通常、変更を自動検出します

インストールの問題：

osgrep doctor              # Diagnose problems
npm install -g osgrep      # Reinstall if needed

結果が見つからない：

• より広いクエリを試してください（「JWT middleware」ではなく「authentication」）
• インデックスが最新であることを確認してください（osgrep index）
• 正しいリポジトリディレクトリにいることを確認してください