Greg Gauthier
d0a4b8922d
Introduce Gitea Actions workflow to automatically move TODO files from queued to completed on PR events for feature branches. Update README with setup instructions and benefits.
542 lines
13 KiB
Markdown
542 lines
13 KiB
Markdown
# Grokkit
|
|
|
|
Grokkit is a fast Go CLI integrating Grok AI with git workflows and general chat/edit functionality.
|
|
|
|
|
|
[]()
|
|
[]()
|
|
[]()
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
grokkit version
|
|
```
|
|
|
|
## 📋 Table of Contents
|
|
|
|
- [Commands](#commands)
|
|
- [Configuration](#configuration)
|
|
- [Workflows](#workflows)
|
|
- [Shell Completions](#shell-completions)
|
|
- [Features](#features)
|
|
- [Development](#development)
|
|
- [Documentation](#documentation)
|
|
- [License](#license)
|
|
|
|
## Commands
|
|
|
|
### 💬 `grokkit chat`
|
|
Interactive CLI chat with Grok. Features persistent history across sessions.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
git add .
|
|
grokkit commit # Generate + confirm + commit
|
|
```
|
|
|
|
### 🔍 `grokkit review`
|
|
AI code review of staged or unstaged changes.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
grokkit history # Last 10 commits
|
|
```
|
|
|
|
### 🤖 `grokkit agent`
|
|
Multi-file agent for complex refactoring (experimental).
|
|
|
|
```bash
|
|
grokkit agent "refactor authentication to use JWT"
|
|
```
|
|
|
|
### 🔧 `grokkit lint FILE`
|
|
Automatically detect language, run linter, and apply AI-suggested fixes.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
export XAI_API_KEY=sk-... # Required: Your xAI API key
|
|
```
|
|
|
|
### Config File (Optional)
|
|
|
|
Create `~/.config/grokkit/config.toml`:
|
|
|
|
```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](docs/CONFIGURATION.md) for advanced configuration options.
|
|
|
|
### Logging
|
|
|
|
Logs are written to `~/.config/grokkit/grokkit.log` in JSON format.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# 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)
|
|
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)
|
|
├── 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
|
|
└── 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:**
|
|
```bash
|
|
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`](.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](https://gitea.example.com/user/settings/tokens) (scope: `repo`).
|
|
- Optional: Branch protection → Require "Auto-complete TODO" status check.
|
|
|
|
**Result**: No manual post-merge steps needed!
|
|
|
|
## Documentation
|
|
|
|
- 📖 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
|
|
- 🏗️ [Architecture Overview](docs/ARCHITECTURE.md) - System design and patterns
|
|
- ⚙️ [Configuration Guide](docs/CONFIGURATION.md) - 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:**
|
|
|
|
```bash
|
|
# 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](docs/TROUBLESHOOTING.md) for more details.**
|
|
|
|
## License
|
|
|
|
[Unlicense](https://unlicense.org/) - Free for any use, no attribution required.
|
|
|
|
---
|
|
|
|
**Made with ❤️ using Grok AI**
|