GrepAI Advanced Search Options Skill

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

| Option | Description | |--------|-------------| | --limit N | Number of results (default: 10) | | --json / -j | JSON output format | | --toon / -t | TOON output format (~50% fewer tokens than JSON) | | --compact / -c | Compact output (no content, works with --json or --toon) |

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

| Format | Tokens (5 results) | Best For | |--------|-------------------|----------| | JSON | ~1,500 | Scripts, parsing | | JSON compact | ~300 | AI agents | | TOON | ~250 | AI agents | | TOON compact | ~150 | Token-constrained AI |

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

| Full Key | Compact Key | Description | |----------|-------------|-------------| | query | q | Search query | | results | r | Results array | | score | s | Similarity score | | file | f | File path | | start_line/end_line | l | Line range ("15-45") | | total | t | Total results |

Combining Options

# 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 Agent Integration

For Claude/GPT Prompts

Use compact mode to minimize tokens:

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

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

Workflow Example

Search for relevant code:

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

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
}

Read specific files: AI reads src/auth/middleware.go:15-45 for full context.

Scripting with 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 Integration

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

# Start MCP server
grepai mcp-serve

MCP tools support JSON (default) or TOON format:

| MCP Tool | Parameters | |----------|------------| | 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 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:

| Format | Approximate Tokens | |--------|-------------------| | Human-readable | ~2,000 | | JSON full | ~1,500 | | JSON compact | ~300 |

When to Use Each Format

| Format | Use Case | |--------|----------| | Human-readable | Manual inspection | | JSON full | Scripts needing content | | JSON compact | AI agents, token-limited contexts |

Piping Results

To File

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

To Another Tool

# 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

Batch Searches

Run multiple searches:

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

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

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 1
fi

Best Practices

Use compact for AI agents: 80% token savings
Use full JSON for scripts: When you need content
Use human-readable for debugging: Easier to read
Limit results appropriately: Don't fetch more than needed
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)

Agent Skills: GrepAI Advanced Search Options

Install this agent skill to your local

Skill Files