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

| 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

```bash
grepai search "authentication" --json
```

Output:
```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
}
```

### Compact JSON (AI Optimized)

```bash
grepai search "authentication" --json --compact
```

Output:
```json
{
  "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

```bash
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)

```bash
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

```bash
# 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:

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

Then provide