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

One-line Install (Recommended)

Bash (Linux/macOS):

export VERSION=0.3.5
curl -fsSL https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh | bash -s -- --verify

PowerShell (Windows):

$env:VERSION="0.3.5"
 irm https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v$env:VERSION/grokkit-install.ps1 | iex

Both installers feature:

• ✅ Automatic platform detection (Linux, macOS, Windows)
• ✅ SHA256 checksum verification
• ✅ Safe extraction to ~/.local/bin or $env:LOCALAPPDATA\bin
• ✅ No temporary files left behind

Download First Approach

Bash (Linux/macOS):

export VERSION=0.3.5
curl -fsSL https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh -o grokkit-install.sh
bash grokkit-install.sh --verify

PowerShell (Windows):

$env:VERSION="0.3.5"
 irm https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v$env:VERSION/grokkit-install.ps1 -OutFile grokkit-install.ps1
 .\grokkit-install.ps1 -Verify

💡 Windows Note: PowerShell installers auto-detect Windows architecture (x86_64, ARM64) and place the binary in %LOCALAPPDATA%\bin\grokkit.exe. Add this path to your PATH if not already present.

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 54%+ - Comprehensive unit tests including all command message builders
• ✅ Coverage gate in CI - Builds fail if coverage drops below 50%
• ✅ 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