grokkit/README.md

# Grokkit

Grokkit is a fast Go CLI integrating Grok AI with git workflows and general chat/edit.

## 🚀 Quick Start

```bash
export XAI_API_KEY=sk-...

# Install from source
git clone https://github.com/yourusername/grokkit.git
cd grokkit
make install

# Or build locally
make build

grokkit --help
```

## 📁 Config (optional)

`~/.config/grokkit/config.toml`:
```toml
default_model = "grok-4"
temperature = 0.7
timeout = 60  # seconds
log_level = "info"  # debug, info, warn, error

[aliases]
beta = "grok-beta-2"

[chat]
history_file = "~/.config/grokkit/chat_history.json"
```

Logs are written to `~/.config/grokkit/grokkit.log` in JSON format for structured analysis.

## Commands

### 💬 `grokkit chat`
Interactive CLI chat with Grok. Features persistent history across sessions.

```
grokkit chat
grokkit chat -m grok-beta  # Use specific model
```

### 📝 `grokkit commitmsg`
Generate conventional commit from staged changes.

```
git add .
grokkit commitmsg
```

### ✅ `grokkit commit`
Generate & commit.

```
grokkit commit
```

### 🔍 `grokkit review`
AI code review of staged changes.

```
grokkit review
```

### 📋 `grokkit pr-describe`
PR description from branch vs main.

```
grokkit pr-describe
```

### 📜 `grokkit history`
Summarize recent commits.

```
grokkit history
```

### ✏️ `grokkit edit FILE "instruction"`
AI edit file.

```
grokkit edit main.go "add error handling"
```

## Shell Completions

Generate shell completions for your shell:

```bash
# Bash
grokkit completion bash > /etc/bash_completion.d/grokkit

# Zsh
grokkit completion zsh > "${fpath[1]}/_grokkit"

# Fish
grokkit completion fish > ~/.config/fish/completions/grokkit.fish

# PowerShell
grokkit completion powershell > grokkit.ps1
```

## Flags

- `--model, -m`: Specify model (e.g., grok-4, grok-beta)
- `--debug`: Enable debug logging (outputs to both stderr and log file)
- `--verbose, -v`: Enable verbose logging
- All flags are global and work with any command

## Features

- ✅ **Structured logging with slog** - JSON logs with request tracing, timing, and context
- ✅ Context-aware HTTP requests with timeouts
- ✅ Comprehensive error handling and custom error types
- ✅ Persistent chat history across sessions
- ✅ Configurable temperature and parameters
- ✅ Shell completions (bash, zsh, fish, powershell)
- ✅ Test coverage >70%
- ✅ CI/CD with Gitea Actions
- ✅ Interface-based design for testability

### Logging & Observability

Grokkit uses Go's standard `log/slog` for structured logging:

```bash
# Enable debug mode (logs to both stderr and file)
grokkit chat --debug

# View logs
tail -f ~/.config/grokkit/grokkit.log

# Parse JSON logs with jq
cat ~/.config/grokkit/grokkit.log | jq 'select(.level=="ERROR")'
```

**Logged metrics:**
- API request/response timing and sizes
- Git command execution and output
- File operations with size tracking
- Error context with stack traces

## Development

```bash
# Run tests
make test

# Run tests with coverage
make test-cover

# Build
make build

# Install locally
make install
```

## License

[Unlicense](https://unlicense.org/)