Grepai Search Advanced

GrepAI Advanced Search Options

This skill covers advanced search options including JSON output, compact mode, and integration with AI agents.

When to Use This Skill

• Integrating GrepAI with scripts or tools
• Using GrepAI with AI agents (Claude, GPT)
• Processing search results programmatically
• Reducing token usage in AI contexts

Command-Line Options

Note: --json and --toon are mutually exclusive.

JSON Output

Standard JSON

grepai search "authentication" --json

Output:

{  "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}

Compact JSON (AI Optimized)

grepai search "authentication" --json --compact

Output:

{  "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}

Key differences:

• Abbreviated keys (s vs score, f vs file)
• No content (just file locations)
• ~80% fewer tokens for AI agents

TOON Output (v0.26.0+)

TOON (Token-Oriented Object Notation) is an even more compact format, optimized for AI agents.

Standard TOON

grepai search "authentication" --toon

Output:

[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

Compact TOON (Best for AI)

grepai search "authentication" --toon --compact

Output:

[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 Comparison

When to Use TOON

• Use TOON when integrating with AI agents that support it
• Use TOON compact for maximum token efficiency (~50% smaller than JSON compact)
• Stick with JSON for traditional scripting (jq, programming languages)

Compact Format Reference

Combining Options

# 5 results in compact JSONgrepai search "error handling" --limit 5 --json --compact
# 20 results in full JSONgrepai search "database" --limit 20 --json

AI Agent Integration

For Claude/GPT Prompts

Use compact mode to minimize tokens:

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

Then provide results to the AI with file read tool for details.

Workflow Example

1. Search for relevant code:

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

2. Get response:

{  "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. Read specific files: AI reads src/auth/middleware.go:15-45 for full context.

Scripting with JSON

Bash + jq

# Get just file pathsgrepai search "config" --json | jq -r '.results[].file'
# Filter by scoregrepai search "config" --json | jq '.results[] | select(.score > 0.8)'
# Count resultsgrepai search "config" --json | jq '.total'

Python

import subprocessimport 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 Integration

GrepAI provides MCP tools with format selection (v0.26.0+):

# Start MCP servergrepai mcp-serve

MCP tools support JSON (default) or TOON format:

Format Parameter

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

Valid values: "json" (default) or "toon"

Token Optimization

Token Comparison

For a typical search with 5 results:

When to Use Each Format

Piping Results

To File

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

To Another Tool

# Open results in VS Codegrepai 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

Batch Searches

Run multiple searches:

#!/bin/bashqueries=("authentication" "database" "logging" "error handling")
for q in "${queries[@]}"; do    echo "=== $q ==="    grepai search "$q" --json --compact --limit 3    echodone

Error Handling

JSON Error Response

When search fails:

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

Checking for Errors in Scripts

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

Best Practices

1. Use compact for AI agents: 80% token savings
2. Use full JSON for scripts: When you need content
3. Use human-readable for debugging: Easier to read
4. Limit results appropriately: Don't fetch more than needed
5. Check for errors: Parse JSON response properly

Output Format

Advanced search output (JSON compact):

{  "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}

Token estimate: ~80 tokens (vs ~800 for full content)