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
}

主な違い:

• 短縮キー (s vs score, f vs file)
• コンテンツなし (ファイル位置のみ)
• 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 vs JSON の比較

形式	トークン数 (5 結果)	最適な用途
JSON	~1,500	スクリプト、パース処理
JSON コンパクト	~300	AI エージェント
TOON	~250	AI エージェント
TOON コンパクト	~150	トークン制約のある AI

TOON を使用する場合

• TOON を使用: これをサポートする AI エージェント統合時
• TOON コンパクトを使用: 最大トークン効率化時 (JSON コンパクトより約 50% 小さい)
• JSON を使用: 従来のスクリプティング時 (jq、プログラミング言語)

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

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

オプションの組み合わせ

# 5 つの結果をコンパクト JSON で取得
grepai search "error handling" --limit 5 --json --compact

# 20 の結果をフル JSON で取得
grepai search "database" --limit 20 --json

AI エージェント統合

Claude/GPT プロンプト向け

コンパクトモードを使用してトークンを最小化します:

# エージェントがコンテキストをリクエスト
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

# ファイルパスのみを取得
grepai search "config" --json | jq -r '.results[].file'

# スコアでフィルタ
grepai search "config" --json | jq '.results[] | select(.score > 0.8)'

# 結果数をカウント
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+):

# MCP サーバーを起動
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

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

別のツールに出力

# VS Code で結果を開く
grepai search "config" --json | jq -r '.results[0].file' | xargs code

# 最初の結果パスをクリップボードにコピー (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 に対して)