# `grokkit agent` pprof integration

**Description**: Go pprof profiling wrappers (CPU/memory/allocs). Captures profiles during agent runs, AI-analyzes hotspots.

## Problem It Solves

Profile.md is high-level; pprof enables raw data + AI opts for slow cmds (agent loops).

## Benefits

- **Capture**: `go test -cpuprofile` or runtime/pprof.
- **Analyze**: Feed pprof text/top to Grok ("Optimize this flamegraph").
- **Safe**: Temp .pprof files, no web UI.
- **Integrate**: Auto-profile long agents.

## Agent Tool Examples

```
grokkit agent "Profile cmd/agent.go benchmark, suggest fixes"
# Grok: pprof cpu → "30% in StreamSilent, batch calls"
```

## High-Level Implementation

1. **Detect**: `go tool pprof --version`.
2. **Tool schemas**:
   - `cpu_profile(duration: int) → pprof_text`
   - `analyze(profile_data: string) → suggestions`
3. **Wrappers** in `internal/tools/pprof.go`:
   ```go
   func CPUProfile(ctx context.Context, args map[string]any) (string, error)
   ```
4. **Agent integration**: Flag-triggered profiling.
5. **Safety**:
   - Tempdir files (os.TempDir).
   - No --http/--pdf.
   - Config: `[tools.pprof.enabled]`.

## Flags / Config

| Key | Description |
|-----|-------------|
| `tools.pprof.enabled` | Enable pprof tools |
| `--profile-cpu` | Auto-cpu on agent |

## Implementation Notes

- **Capture**: runtime/pprof.StartCPUProfile, or `go test -cpuprofile`.
- **Parse**: `go tool pprof -text`.
- **Errors**: PprofError.
- **Tests**: Mock profiles.
- **Effort**: Medium (~180 LOC). Ties to profile.md.
- **Prereq**: Go stdlib pprof.

## ROI

**High** for perf:

| Stage | Covered |
|-------|---------|
| Profile | **pprof** ← new |
| Analyze | profile.md ✓ |