Grokkit

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

🚀 Quick Start

# Set your API key
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

# Verify installation
grokkit --help

📋 Table of Contents

• Commands
• Configuration
• Workflows
• Shell Completions
• Features
• Development
• Documentation
• License

Commands

💬 grokkit chat

Interactive CLI chat with Grok. Features persistent history across sessions.

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.

# 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.

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.

git add .
grokkit commit                  # Generate + confirm + commit

🔍 grokkit review

AI code review of staged or unstaged changes.

# 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.

# 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.

grokkit history                 # Last 10 commits

🤖 grokkit agent

Multi-file agent for complex refactoring (experimental).

grokkit agent "refactor authentication to use JWT"

🔧 grokkit lint FILE

Automatically detect language, run linter, and apply AI-suggested fixes.

# 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

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

Config File (Optional)

Create ~/.config/grokkit/config.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-mini"

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

See also: docs/CONFIGURATION.md for advanced configuration options.

Logging

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

# 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

# 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

# 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

# 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

# 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

# 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
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

# 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:

{
  "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

# Run tests
make test

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

# 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/           # Configuration management (viper)
├── internal/
│   ├── errors/       # Custom error types
│   ├── git/          # Git operations wrapper
│   ├── grok/         # Grok API client
│   └── logger/       # Structured logging (slog)
├── docs/             # Documentation
├── .gitea/           # CI/CD workflows
└── Makefile          # Build automation

Documentation

• 📖 Troubleshooting Guide - Common issues and solutions
• 🏗️ Architecture Overview - System design and patterns
• ⚙️ Configuration Guide - 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+ (for building)
• Git (for git-related commands)
• XAI API key

Troubleshooting

Common issues:

# 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 for more details.

License

Unlicense - Free for any use, no attribution required.

---

Made with ❤️ using Grok AI