grokkit/README.md

Grokkit

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

Requirements

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

🚀 Quick Start Installation

From pre-built release (recommended)

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 -

From Source (for development)

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

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

Verify:

grokkit version

Configuration

Environment Variables

export XAI_API_KEY=sk-...       # Required: Your xAI API key
export XAI_API_KEY=$(vault read -field=key secret/grokkit) # Recommended for secure storage

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-1-fast-non-reasoning"

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

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

📖 Commands

See The User Guide for complete details on command usage.

🛡️ Safety & Change Management

Grokkit is designed to work seamlessly with Git, using version control instead of redundant backup files to manage changes and rollbacks.

Read the Safety & Change Management Guide

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

Common usage patterns to integrate Grokkit into your development cycle.

Read the Workflows Guide

Shell Completions

Generate shell completions for faster command entry:

Read the full Completion Guide

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 - Preview and confirmation, leverage git for rollbacks
• ✅ Git workflow integration - Commit messages, reviews, PR descriptions
• ✅ Multi-language linting - 9 languages supported with AI-powered fixes
• ✅ AI documentation generation - 8 doc styles (godoc, PEP 257, Doxygen, JSDoc, rustdoc, YARD, Javadoc, shell)
• ✅ AI unit test generation - Go (table-driven), Python (pytest), C (Check), C++ (GTest)
• ✅ AI file scaffolding - Create new files with project-aware style matching
• ✅ Transactional Recipes - Markdown-based multi-step AI workflows

Quality & Testing

• ✅ Test coverage 68%+ - Comprehensive unit tests including all command message builders
• ✅ Coverage gate in CI - Builds fail if coverage drops below 65%
• ✅ CI/CD with Gitea Actions - Tests must pass before lint and build jobs run
• ✅ Golangci-lint configured - .golangci.yml with govet, errcheck, staticcheck, and more
• ✅ 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

Comprehensive build instructions, project structure details, and the Grokkit development workflow.

Read the Development Overview Guide

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)

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/developer-guide/TROUBLESHOOTING.md for more details.

License

Unlicense - Free for any use, no attribution required.

---

Made with ❤️ using Grok AI