openviking

OpenViking コードリポジトリ検索

重要：すべての ov コマンドはターミナル（シェル）コマンドです。bash ツール経由で実行してください。直接実行し、事前チェックやテストコマンドは実行しないでください。エラーが発生した場合は対処してください。

OpenViking のデータ整理方法

OpenViking は、viking:// 名前空間の下にある仮想ファイルシステムにコンテンツを保存します。各 URI はファイルまたはディレクトリに対応します（例：viking://resources/fastapi/routing.py）。各ディレクトリには、AI が生成した要約（abstract／overview）があります。重要な原則：URI の範囲を絞ると、検索効率が向上します。 すべてのリポジトリを検索するのではなく、特定のリポジトリまたはサブディレクトリに絞り込むことで、ノイズを減らし、結果を大幅に速く得られます。

検索コマンド

検索対象に応じて適切なコマンドを選択してください。

コマンド	使用する場面	例
ov search	セマンティック検索 — 概念や意図に基づくクエリに使用します	「依存性注入」、「認証の仕組み」
ov grep	正確なキーワードやシンボルがわかっている場合	関数名、クラス名、エラー文字列
ov glob	パターンに一致するファイルを列挙したい場合	すべての *.py ファイル、すべてのテストファイル

# Semantic search
ov search "dependency injection" --uri viking://resources/fastapi --limit 10
ov search "how tokens are refreshed" --uri viking://resources/fastapi/fastapi/security
ov search "JWT authentication" --limit 10          # across all repos
ov search "error handling" --limit 5 --threshold 0.7  # filter low-relevance results

# Keyword search — exact match or regex
ov grep "verify_token" --uri viking://resources/fastapi
ov grep "class.*Session" --uri viking://resources/requests/requests

# File enumeration — by name pattern (always specify --uri to scope the search)
ov glob "**/*.py" --uri viking://resources/fastapi
ov glob "**/test_*.py" --uri viking://resources/fastapi/tests
ov glob "**/*.py" --uri viking://resources/   # across all repos

範囲の絞り込み： 関連するディレクトリを特定したら、それを --uri として指定し、以降の検索をそのサブツリーに制限してください。リポジトリ全体を検索するより速く、正確です。

クエリの作成： 単一のキーワードではなく、具体的で文脈のあるクエリを作成してください。

ov search "API"                                                       # too vague
ov search "REST API authentication with JWT tokens"                   # better
ov search "JWT token refresh flow" --uri viking://resources/backend   # best

コンテンツを読む

# Directories: AI-generated summaries
ov abstract viking://resources/fastapi/fastapi/dependencies/   # one-line summary
ov overview viking://resources/fastapi/fastapi/dependencies/   # detailed breakdown

# Files: raw content
ov read viking://resources/fastapi/fastapi/dependencies/utils.py
ov read viking://resources/fastapi/fastapi/dependencies/utils.py --offset 100 --limit 50

abstract／overview はディレクトリでのみ機能します。read はファイルでのみ機能します。

参照する

ov ls viking://resources/                        # list all indexed repos
ov ls viking://resources/fastapi                 # list repo top-level contents
ov ls viking://resources/fastapi --simple        # paths only, no metadata
ov ls viking://resources/fastapi --recursive     # list all files recursively
ov tree viking://resources/fastapi               # full directory tree (default: 3 levels deep)
ov tree viking://resources/fastapi -L 2          # limit depth to 2 levels
ov tree viking://resources/fastapi -l 200        # truncate abstract column to 200 chars
ov tree viking://resources/fastapi -L 2 -l 200   # combined: 2 levels deep, 200-char summaries

-L はツリーを展開する深さのレベル数を指定します。-l はディレクトリごとの AI 生成要約の長さを指定します。リポジトリの構造を把握してから詳細を確認するには、まず ov tree -L 2 -l 200 を使うとよいでしょう。

リポジトリを追加する

ov add-resource https://github.com/owner/repo --to viking://resources/repo --timeout 300

--timeout は必須です（秒単位）。小規模なリポジトリには 300（5 分）を使用し、大規模な場合は増やしてください。

送信後、ov observer queue を一度実行し、状況をユーザーに報告してください。インデックス作成はバックグラウンドで実行されます。ポーリングや待機はしないでください。

リポジトリの規模	ファイル数	推定時間
小規模	< 100	2～5 分
中規模	100～500	5～20 分
大規模	500+	20～60 分以上

リポジトリを削除する

ov rm viking://resources/fastapi --recursive

これにより、リポジトリとインデックス化されたすべてのコンテンツが完全に削除されます。実行前にユーザーに確認してください。

エラー処理

command not found: ov → ユーザーに pip install openviking --upgrade を伝えてください。そこで終了します。

url is required／CLI_CONFIG エラー → 設定を自動作成して再試行します。

mkdir -p ~/.openviking && echo '{"url": "http://localhost:1933"}' > ~/.openviking/ovcli.conf

CONNECTION_ERROR／接続失敗：

• ~/.openviking/ov.conf が存在する → サーバーを自動起動し、正常な状態になるまで待ってから再試行します。

  openviking-server > /tmp/openviking.log 2>&1 &
  for i in $(seq 1 10); do ov health 2>/dev/null && break; sleep 3; done
  

• 存在しない → まず ~/.openviking/ov.conf を設定するようユーザーに伝えてください。そこで終了します。

詳細情報

その他の問題やコマンドの詳細については、次を実行してください。

ov help
ov <command> --help   # e.g. ov search --help