# `grokkit agent` ripgrep (rg) integration
## Priority: 7 of 12

**Description**: Fast search wrapper for ripgrep (`rg`). Enables agent to grep project for symbols/patterns/context before edits.

## Problem It Solves

Agent lacks quick codebase search—relies on full file scans or manual `grep`. rg is 10x faster, regex-aware.

## Benefits

- **Lightning search**: Multi-line, git-ignored, type-aware (`--type=go`).
- **Context gathering**: "rg 'err handling' → snippets for prompt".
- **Safe**: Read-only, project-only, no filespecs.
- **Stats**: Count matches, paths.
- **Workflow**: "Search todos → prioritize → edit".

## Agent Tool Examples

```
grokkit agent "Find all error returns in cmd/, improve handling"
# Grok: rg 'return err' cmd/ → analyzes → targeted edits
```

```
grokkit agent "Count test coverage gaps: rg 't.Skip' or untested funcs"
# Grok: rg --type=go '_test\.go' → stats → testgen suggestions
```

## High-Level Implementation

1. **Detect**: `rg --version`.
2. **Tool schemas**:
   - `search(pattern: string, path?: string) → matches[]`
   - `count(pattern: string) → int`
3. **Wrappers** in `internal/tools/rg.go`:
   ```go
   func Search(ctx context.Context, args map[string]any) (string, error)
   ```
4. **Agent integration**: Pre-plan search → richer context.
5. **Safety**:
   - Args whitelist: --type, --no-heading, project root.
   - Max 100 matches.
   - Config: `[tools.rg.enabled]`.
6. **Parsing**: JSON output (`--json`), or lines → structured.

## Flags / Config

| Key | Description |
|-----|-------------|
| `tools.rg.enabled` | Enable rg tools |
| `tools.rg.max_matches` | Limit results |

## Implementation Notes

- **Commands**: `rg PATTERN [PATH] --no-heading --colors=never`.
- **Extend agent**: Optional search phase in planning.
- **Errors**: RgError.
- **Tests**: Mock, table-driven patterns.
- **Effort**: Low (~100 LOC).
- **Prereq**: rg installed (`apt install ripgrep`).

## ROI

**High**. Search is dev superpower:

| Stage | Covered |
|-------|---------|
| Search | **rg** ← new |
| Edit | `agent` ✓ |
| Verify | make (sibling) |

Agent plans smarter with instant intel.