grokkit/README.md

# Grokkit

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


[![Test Coverage](https://img.shields.io/badge/coverage-72%25-brightgreen)]()
[![Go Version](https://img.shields.io/badge/go-1.24.2-blue)]()
[![License](https://img.shields.io/badge/license-Unlicense-lightgrey)]()

## 🚀 Quick Start

```bash
# Set your API key
export XAI_API_KEY=sk-...

# Install from source
git clone https://repos.gmgauthier.com/gmgauthier/grokkit.git
cd grokkit
make install

# Or build locally
make build

# Verify installation
grokkit --help

### From pre-built release (recommended)
```bash
VERSION=0.1.3  # Replace with latest version tag (omit 'v')
curl -L https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh | VERSION=${VERSION} bash -
```
Verify:
```bash
grokkit version
```

## 📋 Table of Contents

- [Commands](#commands)
- [Configuration](#configuration)
- [Workflows](#workflows)
- [Shell Completions](#shell-completions)
- [Features](#features)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)

## Commands

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

```bash
grokkit chat                    # Start chat session
grokkit chat -m grok-beta       # Use specific model
grokkit chat --debug            # Enable debug logging
```

**Tips:**
- Type `/quit`, `/q`, or `exit` to exit
- History is saved automatically between sessions
- Use `--debug` to see API request timing

### ✏️ `grokkit edit FILE "instruction"`
AI-powered file editing with preview and automatic backups.

```bash
# Basic usage
grokkit edit main.go "add error handling to all functions"

# Complex refactoring
grokkit edit server.go "convert this to use context for cancellation"

# Add features
grokkit edit api.go "add rate limiting middleware"

# Documentation
grokkit edit utils.go "add detailed docstrings to all exported functions"
```

**Safety features:**
- Creates `.bak` backup before any changes
- Shows preview with diff-style output
- Requires confirmation before applying
- Uses silent streaming (no console spam)

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

```bash
git add .
grokkit commitmsg               # Generate message only
grokkit commitmsg -m grok-4     # Use specific model
```

Output format: `type(scope): subject\n\nbody`

### ✅ `grokkit commit`
Generate commit message and commit in one step.

```bash
git add .
grokkit commit                  # Generate + confirm + commit
```

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

```bash
# Review staged changes
git add feature.go
grokkit review

# Review all changes
grokkit review

# Get detailed review
grokkit review --debug          # See API timing info
```

Output includes:
- Summary of changes
- 3-5 actionable improvements
- Potential bugs or issues
- Best practice suggestions

### 📋 `grokkit pr-describe`
Generate comprehensive PR descriptions.

```bash
# From current branch vs main
grokkit pr-describe

# With specific model
grokkit pr-describe -m grok-4
```

Output includes:
- Title suggestion
- Summary of changes
- Motivation/context
- Testing notes

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

```bash
grokkit history                 # Last 10 commits
```

### 🤖 `grokkit agent`
Multi-file agent for complex refactoring (experimental).

```bash
grokkit agent "refactor authentication to use JWT"
```

### 🔧 `grokkit lint FILE`
Automatically detect language, run linter, and apply AI-suggested fixes.

```bash
# Just check for issues (no fixes)
grokkit lint main.go --dry-run

# Interactive fix (preview + confirmation)
grokkit lint app.py

# Auto-fix without confirmation
grokkit lint server.js --auto-fix

# Use specific model
grokkit lint script.rb -m grok-4
```

**Supported languages:**
- **Go** (golangci-lint, go vet)
- **Python** (pylint, flake8, ruff)
- **JavaScript/JSX** (eslint)
- **TypeScript/TSX** (eslint, tsc)
- **Rust** (clippy)
- **Ruby** (rubocop)
- **Java** (checkstyle)
- **C/C++** (clang-tidy)
- **Shell** (shellcheck)

**Safety features:**
- Creates `.bak` backup before changes
- Shows preview of fixes
- Verifies fixes by re-running linter
- Requires confirmation (unless `--auto-fix`)

## Configuration

### Environment Variables

```bash
export XAI_API_KEY=sk-...       # Required: Your xAI API key
```

### Config File (Optional)

Create `~/.config/grokkit/config.toml`:

```toml
default_model = "grok-4"
temperature = 0.7
timeout = 60                    # API timeout in seconds
log_level = "info"              # debug, info, warn, error

[aliases]
beta = "grok-beta-2"
fast = "grok-4-1-fast-non-reasoning"

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

**See also:** [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for advanced configuration options.

### Logging

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

```bash
# View logs in real-time
tail -f ~/.config/grokkit/grokkit.log

# Find errors
cat ~/.config/grokkit/grokkit.log | jq 'select(.level=="ERROR")'

# Track API performance
cat ~/.config/grokkit/grokkit.log | jq 'select(.msg=="API request completed") | {model, duration_ms, response_length}'
```

## Workflows

### Git Workflow Integration

```bash
# 1. Make changes
vim src/api.go

# 2. Review with AI
git add src/api.go
grokkit review

# 3. Fix issues, then commit
git add src/api.go
grokkit commit

# 4. Generate PR description
grokkit pr-describe
```

### Code Refactoring Workflow

```bash
# 1. Chat to plan approach
grokkit chat
> "How should I refactor this authentication code to use middleware?"

# 2. Apply changes with edit
grokkit edit auth.go "implement middleware pattern as discussed"

# 3. Review changes
grokkit review

# 4. Commit
grokkit commit
```

### Debugging Workflow

```bash
# 1. Describe issue in chat
grokkit chat --debug
> "I'm getting a nil pointer error in handler.go:42"

# 2. Apply suggested fixes
grokkit edit handler.go "add nil checks before dereferencing user object"

# 3. Verify and commit
grokkit review
grokkit commit
```

### Batch File Editing

```bash
# Edit multiple files with consistent changes
for file in src/*.go; do
  grokkit edit "$file" "add context parameter to all exported functions"
done

# Review all changes together
grokkit review
```

### Code Quality Workflow

```bash
# 1. Check a file for linting issues
grokkit lint app.py --dry-run

# 2. Apply AI-suggested fixes with preview
grokkit lint app.py

# 3. Auto-fix multiple files
for file in src/*.js; do
  grokkit lint "$file" --auto-fix
done

# 4. Review and commit
grokkit review
grokkit commit
```

## Shell Completions

Generate shell completions for faster command entry:

```bash
# Bash
grokkit completion bash | sudo tee /etc/bash_completion.d/grokkit

# Zsh (oh-my-zsh)
grokkit completion zsh > ~/.oh-my-zsh/completions/_grokkit

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

# PowerShell
grokkit completion powershell | Out-String | Invoke-Expression
```

## Flags

### Global Flags (work with all commands)

| Flag | Short | Description |
|------|-------|-------------|
| `--model` | `-m` | Override model (e.g., grok-4, grok-beta) |
| `--debug` | | Enable debug logging (stderr + file) |
| `--verbose` | `-v` | Enable verbose logging |
| `--help` | `-h` | Show help |

### Examples

```bash
# Use different model
grokkit chat -m grok-beta

# Debug API issues
grokkit edit main.go "refactor" --debug

# Verbose logging
grokkit review -v
```

## Features

### Core Features
- ✅ **Structured logging with slog** - JSON logs with request tracing, timing, and context
- ✅ **Context-aware HTTP requests** - 60s timeout, proper cancellation
- ✅ **Comprehensive error handling** - Custom error types with context
- ✅ **Persistent chat history** - Never lose your conversations
- ✅ **Configurable parameters** - Temperature, timeout, model selection
- ✅ **Shell completions** - Bash, Zsh, Fish, PowerShell
- ✅ **Safe file editing** - Automatic backups, preview, confirmation
- ✅ **Git workflow integration** - Commit messages, reviews, PR descriptions
- ✅ **Multi-language linting** - 9 languages supported with AI-powered fixes

### Quality & Testing
- ✅ **Test coverage 72%** - Comprehensive unit tests
- ✅ **CI/CD with Gitea Actions** - Automated testing and builds
- ✅ **Interface-based design** - Testable and maintainable
- ✅ **Zero external dependencies** - Only stdlib + well-known libs

### Observability

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

**Example log entry:**
```json
{
  "time": "2026-03-01T10:30:47.890Z",
  "level": "INFO",
  "msg": "API request completed",
  "model": "grok-4",
  "response_length": 1024,
  "chunks_received": 42,
  "duration_ms": 2434,
  "duration": "2.434s"
}
```

## Development

```bash
# All tests pass without XAI_API_KEY (unit tests only)

# Run tests
make test

# Agent-specific tests
make test-agent

# Run tests with coverage report
make test-cover
open build/coverage.html

# Linting (matches CI)
make lint
# Install golangci-lint if needed:
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run specific tests
go test -run TestEditCommand ./cmd -v

# Build binary
make build

# Install locally
make install

# Clean build artifacts
make clean
```

### Project Structure

```
grokkit/
├── cmd/              # CLI commands (Cobra)
├── config/           # Viper configuration
├── docs/             # Documentation
├── todo/              # TODO tracking: queued/ (pending) and completed/ (historical record)
│   ├── queued/        # Pending TODO items
│   └── completed/     # Completed TODO items with history
├── internal/
│   ├── errors/       # Custom error types
│   ├── git/          # Git operations
│   ├── grok/         # xAI Grok API client
│   ├── linter/       # Multi-language linting
│   ├── logger/       # Structured slog logging
│   └── version/      # Build/version info
├── main.go           # Application entrypoint
├── go.mod            # Dependencies
├── Makefile          # Build automation
└── scripts/          # Install scripts
```

### TODO Workflow

**Policy:**  
From now on, the only thing to be committed directly to the `master` branch will be to-do items (.md files in `todo/queued/`).

**Process:**  
1. When deciding to work on a to-do item: create a branch, implement on the branch, submit PR to `master`.  
2. After PR merge: move the item to `todo/completed/`.

**Example workflow:**  
```bash
git checkout -b feature/some-todo
# Implement changes, test with make test lint
git add .
git commit -m "feat: implement some-todo"
git push -u origin feature/some-todo
# Create and merge PR to master

# Post-merge:
git checkout master
git pull
mv "todo/queued/SOME_TODO.md" "todo/completed/SOME_TODO.md"
git add todo/
git commit -m "chore: complete some-todo"
git push origin master
```

## Documentation

- 📖 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
- 🏗️ [Architecture Overview](docs/ARCHITECTURE.md) - System design and patterns
- ⚙️ [Configuration Guide](docs/CONFIGURATION.md) - Advanced configuration options

## API Usage & Costs

Grokkit uses the xAI Grok API. Be aware:
- API calls consume credits/tokens
- Default timeout: 60 seconds
- Streaming reduces perceived latency
- Consider using model aliases for different use cases (fast/expensive)

## Requirements

- Go 1.24.2 (for building)
- Git (for git-related commands)
- XAI API key

## Troubleshooting

**Common issues:**

```bash
# API key not set
Error: XAI_API_KEY environment variable not set
→ Solution: export XAI_API_KEY=sk-your-key

# Request timeout
Error: Request failed: context deadline exceeded
→ Solution: Increase timeout in config.toml or check network

# Permission denied on log file
→ Solution: chmod 644 ~/.config/grokkit/grokkit.log
```

**See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more details.**

## License

[Unlicense](https://unlicense.org/) - Free for any use, no attribution required.

---

**Made with ❤️ using Grok AI**