Grepai Search Basics

# GrepAI Search Basics

This skill covers the fundamentals of semantic code search with GrepAI.

## When to Use This Skill

- Learning GrepAI search
- Performing basic code searches
- Understanding semantic vs. text search
- Interpreting search results

## Prerequisites

1. GrepAI initialized (`grepai init`)
2. Index created (`grepai watch`)
3. Embedding provider running (Ollama, etc.)

## What is Semantic Search?

Unlike traditional text search (grep, ripgrep), GrepAI searches by **meaning**:

| Type | How it Works | Example |
|------|--------------|---------|
| **Text search** | Exact string match | "login" → finds "login" |
| **Semantic search** | Meaning similarity | "authenticate user" → finds login, auth, signin code |

## Basic Search Command

```bash
grepai search "your query here"
```

### Example

```bash
grepai search "user authentication flow"
```

Output:
```
Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatus(401)
            return
        }
        claims, err := ValidateToken(token)
        if err != nil {
            c.AbortWithStatus(401)
            return
        }
        c.Set("user", claims.UserID)
        c.Next()
    }
}

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
func ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        return []byte(secretKey), nil
    })
    if err != nil {
        return nil, err
    }
    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
        return claims, nil
    }
    return nil, errors.New("invalid token")
}

Score: 0.76 | src/handlers/login.go:10-35
──────────────────────────────────────────
func HandleLogin(c *gin.Context) {
    var req LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": "invalid request"})
        return
    }
    user, err := userService.Authenticate(req.Email, req.Password)
    // ...
}
```

## Understanding Results

### Result Format

```
Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[code content]
```

| Component | Meaning |
|-----------|---------|
| **Score** | Similarity (0.0 to 1.0, higher = more relevant) |
| **File path** | Location of the code |
| **Line numbers** | Start-end lines of the chunk |
| **Content** | The actual code |

### Score Interpretation

| Score | Meaning |
|-------|---------|
| 0.90+ | Excellent match |
| 0.80-0.89 | Good match |
| 0.70-0.79 | Related |
| 0.60-0.69 | Loosely related |
| <0.60 | Weak match |

## Limiting Results

By default, GrepAI returns 10 results. Adjust with `--limit`:

```bash
# Get only top 3 results
grepai search "database queries" --limit 3

# Get more results
grepai search "error handling" --limit 20
```

## Checking Index Status

Before searching, verify your index:

```bash
grepai status
```

Output:
```
✅ GrepAI Status

   Index:
   - Files: 245
   - Chunks: 1,234
   - Last updated: 2 minutes ago

   Ready for search.
```

## Search vs Grep Comparison

### Traditional grep

```bash
grep -r "authenticate" .
```
- Finds exact text "authenticate"
- Misses synonyms (login, signin, auth)
- Returns all matches, unranked

### GrepAI search

```bash
grepai search "authenticate user credentials"
```
- Finds semantically similar code
- Includes related concepts
- Results ranked by relevance

## What Makes a Good Query

### Good Queries ✅

Describe the intent or behavior:

```bash
grepai search "validate user credentials"
grepai search "handle HTTP request errors"
grepai search "connect to the database"
grepai search "send emai