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)