grepai-search-advanced

GrepAI の高度な検索オプション

このスキルでは、JSON 出力、コンパクトモード、AI エージェントとの連携など、高度な検索オプションを扱います。

このスキルを使用する場面

• GrepAI をスクリプトやツールと連携する場合
• GrepAI を AI エージェント（Claude、GPT）と使用する場合
• 検索結果をプログラムで処理する場合
• AI のコンテキストでのトークン使用量を削減する場合

コマンドラインオプション

オプション	説明
--limit N	結果の件数（デフォルト：10）
--json / -j	JSON 出力形式
--toon / -t	TOON 出力形式（JSON より約 50％少ないトークン数）
--compact / -c	コンパクト出力（内容なし。--json または --toon と併用）

注： --json と --toon は同時に指定できません。

JSON 出力

標準 JSON

grepai search "authentication" --json

出力：

{
  "query": "authentication",
  "results": [
    {
      "score": 0.89,
      "file": "src/auth/middleware.go",
      "start_line": 15,
      "end_line": 45,
      "content": "func AuthMiddleware() gin.HandlerFunc {\n    return func(c *gin.Context) {\n        token := c.GetHeader(\"Authorization\")\n        if token == \"\" {\n            c.AbortWithStatus(401)\n            return\n        }\n        claims, err := ValidateToken(token)\n        ...\n    }\n}"
    },
    {
      "score": 0.82,
      "file": "src/auth/jwt.go",
      "start_line": 23,
      "end_line": 55,
      "content": "func ValidateToken(tokenString string) (*Claims, error) {\n    ..."
    }
  ],
  "total": 2
}

コンパクト JSON（AI に最適化）

grepai search "authentication" --json --compact

出力：

{
  "q": "authentication",
  "r": [
    {
      "s": 0.89,
      "f": "src/auth/middleware.go",
      "l": "15-45"
    },
    {
      "s": 0.82,
      "f": "src/auth/jwt.go",
      "l": "23-55"
    }
  ],
  "t": 2
}

主な違い：

• キーが短縮されています（score に対する s、file に対する f）
• 内容はなく、ファイルの場所のみが含まれます
• AI エージェントのトークン数を約 80％削減します

TOON 出力（v0.26.0+）

TOON（Token-Oriented Object Notation）は、AI エージェント向けに最適化された、さらにコンパクトな形式です。

標準 TOON

grepai search "authentication" --toon

出力：

[2]{content,end_line,file_path,score,start_line}:
  "func AuthMiddleware()...",45,src/auth/middleware.go,0.89,15
  "func ValidateToken()...",55,src/auth/jwt.go,0.82,23

コンパクト TOON（AI に最適）

grepai search "authentication" --toon --compact

出力：

[2]{end_line,file_path,score,start_line}:
  45,src/auth/middleware.go,0.89,15
  55,src/auth/jwt.go,0.82,23

TOON と JSON の比較

形式	トークン数（5 件の結果）	最適な用途
JSON	約 1,500	スクリプト、解析
JSON コンパクト	約 300	AI エージェント
TOON	約 250	AI エージェント
TOON コンパクト	約 150	トークン数に制約のある AI

TOON を使用する場面

• TOON に対応した AI エージェントと連携する場合は、TOON を使用します
• トークン効率を最大限に高める場合は、TOON コンパクトを使用します（JSON コンパクトより約 50％小さくなります）
• 従来のスクリプト（jq、プログラミング言語）では、JSON を使用します

コンパクト形式のリファレンス

完全なキー	コンパクトキー	説明
query	q	検索クエリ
results	r	結果の配列
score	s	類似度スコア
file	f	ファイルパス
start_line/end_line	l	行の範囲（「15-45」）
total	t	結果の総数

オプションの組み合わせ

# 5 results in compact JSON
grepai search "error handling" --limit 5 --json --compact

# 20 results in full JSON
grepai search "database" --limit 20 --json

AI エージェントとの連携

Claude/GPT のプロンプト向け

トークン数を最小限に抑えるには、コンパクトモードを使用します。

# Agent asks for context
grepai search "payment processing" --json --compact --limit 5

その後、詳細を確認できるよう、ファイル読み取りツールを使って結果を AI に渡します。

ワークフローの例

1. 関連するコードを検索します：

grepai search "authentication middleware" --json --compact --limit 3

2. 応答を取得します：

{
  "q": "authentication middleware",
  "r": [
    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},
    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}
  ],
  "t": 3
}

3. 特定のファイルを読み取ります： AI が src/auth/middleware.go:15-45 を読み取り、全体のコンテキストを確認します。

JSON を使ったスクリプト作成

Bash + jq

# Get just file paths
grepai search "config" --json | jq -r '.results[].file'

# Filter by score
grepai search "config" --json | jq '.results[] | select(.score > 0.8)'

# Count results
grepai search "config" --json | jq '.total'

Python

import subprocess
import json

result = subprocess.run(
    ['grepai', 'search', 'authentication', '--json'],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
for r in data['results']:
    print(f"{r['score']:.2f} | {r['file']}:{r['start_line']}")

Node.js

const { execSync } = require('child_process');

const output = execSync('grepai search "authentication" --json');
const data = JSON.parse(output);

data.results.forEach(r => {
    console.log(`${r.score.toFixed(2)} | ${r.file}:${r.start_line}`);
});

MCP との連携

GrepAI は、形式を選択できる MCP ツールを提供します（v0.26.0+）。

# Start MCP server
grepai mcp-serve

MCP ツールは、JSON（デフォルト）または TOON 形式に対応しています。

MCP ツール	パラメーター
grepai_search	query、limit、compact、format
grepai_trace_callers	symbol、compact、format
grepai_trace_callees	symbol、compact、format
grepai_trace_graph	symbol、depth、format
grepai_index_status	format

形式パラメーター

{
  "name": "grepai_search",
  "arguments": {
    "query": "authentication",
    "format": "toon",
    "compact": true
  }
}

有効な値：「json」（デフォルト）または「toon」

トークンの最適化

トークン数の比較

一般的な検索で 5 件の結果が得られる場合：

形式	概算トークン数
人間が読みやすい形式	約 2,000
JSON フル	約 1,500
JSON コンパクト	約 300

形式の使い分け

形式	用途
人間が読みやすい形式	手動での確認
JSON フル	内容が必要なスクリプト
JSON コンパクト	AI エージェント、トークン数に制限のあるコンテキスト

結果のパイプ処理

ファイルへの出力

grepai search "authentication" --json > results.json

別のツールへの出力

# Open results in VS Code
grepai search "config" --json | jq -r '.results[0].file' | xargs code

# Copy first result path to clipboard (macOS)
grepai search "config" --json | jq -r '.results[0].file' | pbcopy

一括検索

複数の検索を実行します。

#!/bin/bash
queries=("authentication" "database" "logging" "error handling")

for q in "${queries[@]}"; do
    echo "=== $q ==="
    grepai search "$q" --json --compact --limit 3
    echo
done

エラー処理

JSON エラーレスポンス

検索が失敗した場合：

{
  "error": "Index not found. Run 'grepai watch' first.",
  "code": "INDEX_NOT_FOUND"
}

スクリプトでのエラー確認

result=$(grepai search "query" --json)
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
    echo "Error: $(echo "$result" | jq -r '.error')"
    exit 1
fi

ベストプラクティス

1. AI エージェントにはコンパクト形式を使用します： トークンを80％節約できます
2. スクリプトには完全なJSONを使用します： コンテンツが必要な場合に適しています
3. デバッグには人間が読みやすい形式を使用します： 読みやすくなります
4. 結果の件数を適切に制限します： 必要以上に取得しないでください
5. エラーを確認します： JSONレスポンスを適切に解析してください

出力形式

高度な検索の出力（コンパクトなJSON）：

{
  "q": "authentication middleware",
  "r": [
    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},
    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}
  ],
  "t": 3
}

トークンの目安： 約80トークン（完全なコンテンツの場合は約800トークン）