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

grokkit version

📋 Table of Contents

• Commands
  • chat
  • edit
  • commit / commitmsg
  • review
  • pr-describe
  • history
  • lint
  • docs
  • agent
• 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 docs <file> [file...]

Generate language-appropriate documentation comments using Grok AI.

# Preview and confirm
grokkit docs main.go

# Auto-apply without confirmation
grokkit docs handlers.go models.go --auto-apply

# Document multiple files at once
grokkit docs cmd/*.go --auto-apply

# Use specific model
grokkit docs app.py -m grok-4

Supported doc styles by language:

Language	Style
Go	godoc (// FuncName does...)
Python	PEP 257 docstrings ("""Summary\n\nArgs:...""")
C / C++	Doxygen (/** @brief ... @param ... @return ... */)
JavaScript / TypeScript	JSDoc (/** @param {type} name ... */)
Rust	rustdoc (/// Summary\n/// # Arguments)
Ruby	YARD (# @param [Type] name)
Java	Javadoc (/** @param ... @return ... */)
Shell	Shell comments (# function: desc, # Args: ...)

Safety features:

• Creates .bak backup before any changes
• Shows first 50 lines of documented code as preview
• Requires confirmation (unless --auto-apply)

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

[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

Documentation Generation Workflow

# 1. Preview docs for a single file
grokkit docs internal/api/handler.go

# 2. Batch-document a package
grokkit docs cmd/*.go --auto-apply

# 3. Document across languages in one pass
grokkit docs lib/utils.py src/helpers.ts --auto-apply

# 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
• ✅ AI documentation generation - 8 doc styles (godoc, PEP 257, Doxygen, JSDoc, rustdoc, YARD, Javadoc, shell)

Quality & Testing

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

# 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, uses .golangci.yml config)
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)
│   ├── docs.go       # grokkit docs — AI documentation generation
│   ├── lint.go       # grokkit lint — AI-powered linting
│   └── ...           # chat, edit, commit, review, history, pr-describe, agent
├── 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
├── .golangci.yml     # Golangci-lint configuration
└── 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:

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

Gitea Actions Automation (automates post-merge above)

.gitea/workflows/auto-complete-todo.yml triggers on PR opened/synchronize:

• Branches feature/some-todo: moves todo/queued/some-todo.md → completed/.

One-time setup (Gitea → Repo → Settings → Secrets & Variables → Actions):

• New Secret: PAT_TOKEN = Personal Access Token (scope: repo).
• Optional: Branch protection → Require "Auto-complete TODO" status check.

Result: No manual post-merge steps needed!

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.2 (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