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
  • query
  • edit
  • commit / commitmsg
  • review
  • pr-describe
  • history
  • changelog
  • lint
  • docs
  • testgen
  • 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 query

One-shot technical question answering. Perfect for quick programming or engineering questions.

# Basic usage
grokkit query "How do I sort a slice of structs by a field in Go?"

# Longer, more detailed answer
grokkit query --wordy "Explain how Go's context package works with cancellation"

Features:

Default mode is concise, factual, and actionable --wordy flag gives longer, more explanatory answers Uses the fast non-reasoning model by default for speed No persistent history or interactive chat UI

✏️ grokkit edit FILE "instruction"

AI-powered file editing with preview.

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

• 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 changelog

Generate a clean CHANGELOG.md section from git history, designed specifically so the output can be pasted directly into Gitea release notes.

# 1. Create your version tag first
git tag v0.2.0

# 2. Generate preview + write (with safety confirmation)
grokkit changelog

# 3. Output ONLY the new section (perfect for Gitea "Release notes")
grokkit changelog --stdout

# 4. Write file + get commit reminder
grokkit changelog --commit

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

• Shows first 50 lines of documented code as preview
• Requires confirmation (unless --auto-apply)

🧪 grokkit testgen PATHS...

Description: Generate comprehensive unit tests for Go/Python/C/C++ files using AI.

Benefits:

• Go: Table-driven t.Parallel() matching codebase.
• Python: Pytest with @parametrize.
• C: Check framework suites.
• C++: Google Test EXPECT_*.
• Boosts coverage; safe preview.

CLI examples:

grokkit testgen internal/grok/client.go
grokkit testgen app.py --yes
grokkit testgen foo.c bar.cpp

Safety features:

• Lang detection via internal/linter.
• Unified diff preview.
• Y/N (--yes auto).

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

• Shows preview of fixes
• Verifies fixes by re-running linter
• Requires confirmation (unless --auto-fix)

Safety & Change Management

Grokkit is designed to work seamlessly with Git. Rather than creating redundant .bak files, we lean on Git's powerful version control to manage changes and rollbacks.

The Safety Workflow

1. Preview: Every command that modifies files (like edit, lint, docs) shows a diff-style preview first.
2. Confirm: You must explicitly confirm (y/N) before any changes are written to disk.
3. Git Integration: Use Git to manage the "pre-staged," "staged," and "committed" degrees of change.

Managing Undesired Changes

If you've applied a change that you don't like, Git makes it easy to roll back:

• Unstaged changes: If you haven't git add-ed the changes yet:

  git restore <file>
  

• Staged changes: If you've already staged the changes:

  git restore --staged <file>
  git restore <file>
  

• Committed changes: If you've already committed the changes:

  git revert HEAD
  # or to reset to a previous state:
  git reset --hard HEAD~1
  

By using Git, you have a complete audit trail and multiple levels of undo, ensuring your codebase remains stable even when experimenting with AI-driven refactors.

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

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

# 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