grokkit/README.md

# Grokkit

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


[![Test Coverage](https://img.shields.io/badge/coverage-68%25-brightgreen)]()
[![Go Version](https://img.shields.io/badge/go-1.24.2-blue)]()
[![License](https://img.shields.io/badge/license-Unlicense-lightgrey)]()

## 🚀 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)
  - [chat](#-grokkit-chat)
  - [edit](#-grokkit-edit-file-instruction)
  - [commit / commitmsg](#-grokkit-commitmsg)
  - [review](#-grokkit-review)
  - [pr-describe](#-grokkit-pr-describe)
  - [history](#-grokkit-history)
  - [changelog](#-grokkit-changelog)
  - [lint](#-grokkit-lint-file)
  - [docs](#-grokkit-docs-file)
  - [testgen](#-grokkit-testgen)
  - [agent](#-grokkit-agent)
- [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 chat --agent`

**Interactive Agent Mode** — the new primary way to work with Grok on code.

Grok can now call tools directly (`edit`, `scaffold`, `testgen`, `lint`, `commit`) while maintaining full conversation history and safety previews.

```bash
grokkit chat --agent
```
- Uses the fast non-reasoning model for tool reliability
- Every tool action shows a preview and requires explicit confirmation (y/n)
- Persistent session — you can iterate, reject changes, or give follow-up instructions
- Normal grokkit chat (without --agent) remains unchanged (full reasoning model for thoughtful conversation)

**Note**: The old `grokkit agent` command is deprecated and will be removed in v0.3.0. Please migrate to chat --agent.


### ✏️ `grokkit edit FILE "instruction"`
AI-powered file editing with preview.

```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:**
- 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 changelog`

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

```bash
# 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.

```bash
# 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**:
```bash
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).

```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:**
- 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:
  ```bash
  git restore <file>
  ```
- **Staged changes**: If you've already staged the changes:
  ```bash
  git restore --staged <file>
  git restore <file>
  ```
- **Committed changes**: If you've already committed the changes:
  ```bash
  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

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

### Documentation Generation Workflow

```bash
# 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
# 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** - 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:**
```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, 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:**  
```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**