vexor-cli

Vexor CLI スキル

目的

ファイルの正確なテキストではなく、意図（ファイルが何をするか）に基づいてファイルを検索します。

使い方

• 意図に基づくファイルの検索には、まず vexor を使います。
• vexor が見つからない場合は、references/install-vexor.md に従ってください。

コマンド

vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-pattern <PATTERN>] [--top 5] [--content] [--format rich|porcelain|porcelain-z|json]

よく使うフラグ

• --path/-p：ルートディレクトリ（デフォルト：現在のディレクトリ）
• --mode/-m：インデックス作成／検索の方式
• --ext/-e：ファイル拡張子を限定（例：.py,.md）
• --exclude-pattern：gitignore 形式のパターンでパスを除外（繰り返し指定可能。.js → **/*.js）
• --top/-k：結果の件数
• --include-hidden：ドットファイルを含める
• --no-respect-gitignore：無視対象のファイルを含める
• --no-respect-gitignore を指定しても、.vexorignore のプロジェクトルールは常に適用されます。
• --no-recursive：トップディレクトリのみを対象にする
• --format：スクリプト向けの porcelain／porcelain-z、チャンクの内容を含む完全な出力の json、または rich（デフォルト）
• --content：各一致結果のソーステキストをテーブルの下に表示します。通常、その後にファイルを読む必要がなくなります。
• --no-cache：メモリ内のみで処理し、インデックスキャッシュを読み書きしません。
• vexor index --local：プロジェクトローカルの .vexor/ キャッシュストレージを作成して使用します。

プロジェクト設定

• 最も近い .vexor/config.json が、解決された検索パスまたはインデックスパスに自動的に適用されます。
• 設定できるのは rerank、auto_index、model、embedding_dimensions、batch_size、embed_concurrency、extract_concurrency のみです。
• batch_size は 0 以上、両方の同時実行数は 1 以上である必要があります。
• 認証情報とエンドポイント（api_key、base_url、remote_rerank）、およびその他すべてのフィールドは拒否されます。
• 優先順位は、グローバル設定、プロジェクト設定、環境変数による上書き、明示的な引数の順です。
• vexor config --show は各フィールドの設定元を表示し、vexor doctor は有効な上書きを一覧表示します。設定を変更する vexor config コマンドは引き続きグローバル設定のみを対象にします。

モード（要件を満たす中で最も低コストなものを選択）

• auto：ファイルの種類に応じて振り分けます（デフォルト）
• name：ファイル名のみを対象にします（最速）
• head：先頭の行のみを対象にします（高速）
• brief：キーワードの要約を対象にします（PRD に適しています）
• code：.py/.js/.ts 向けのコード認識チャンク分割（コードベースのデフォルトとして最適）
• outline：Markdown の見出し／セクションを対象にします（ドキュメントに最適）
• full：ファイル全体をチャンクに分割します（最も遅いものの、再現率が最も高い）

トラブルシューティング

• 関数名／クラス名／定数名などの識別子を完全一致で検索しても結果が少ない場合は、vexor config --rerank hybrid を一度提案してください。完全一致の字句検索とセマンティック検索を統合します。
• 無視対象または隠しファイルが必要な場合は、--include-hidden および／または --no-respect-gitignore を追加します。
• スクリプト向けの出力には、--format porcelain（TSV）または --format porcelain-z（NUL 区切り）を使います。
• 詳細なヘルプを表示するには、vexor search --help を使います。
• 設定に問題がある場合は、vexor doctor または vexor config --show で有効な値とその設定元を確認できます。

例

# Find CLI entrypoints / commands
vexor search "typer app commands" --top 5

# Search docs by headings/sections
vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain

# Locate config loading/validation logic
vexor search "config loader" --path . --mode code --ext .py

# Exclude tests and JavaScript files
vexor search "config loader" --path . --exclude-pattern tests/** --exclude-pattern .js

# Read the matching code directly, without a follow-up file read
vexor search "where JWT claims are validated" --path . --mode code --content

ヒント

• 初回の検索ではファイルのインデックスが作成されます（1 分ほどかかることがあります）。長時間実行される MCP または Python クライアントのセッションでは、マッピング済みのベクトルを再利用し、ソースの変更を監視して、一部のスナップショットスキャンを省略します。ウォッチャーのセットアップに失敗した場合は、スキャンにフォールバックします。CLI を個別に実行するたびに、ファイルシステムの検証は行われます。必要に応じて、タイムアウトを長めに設定してください。
• 結果には、類似度による順位、正確なファイル位置、行番号、一致した箇所のプレビューが表示されます。
• --content（または --format json）を追加すると、同じ呼び出しで一致したソーステキストを取得でき、ファイルを個別に読む必要がなくなります。テキストの範囲は content_start_line..content_end_line です。長いシンボルが複数のチャンクとしてインデックス化されている場合、開始位置は結果の start_line より後になることがあります。結果に stale_line_range が表示された場合は、インデックス作成後にファイルが変更されています。vexor index を再実行してください。応答ごとにコンテンツ量の上限があるため、順位の低い結果では budget_exhausted が報告されることがあります。
• --ext と --exclude-pattern を組み合わせて対象を絞り込めます（除外ルールは絞り込んだ対象に適用されます）。