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

## Requirements

- Go 1.24.2 (for building)
- Git (for git-related commands)
- XAI API key

## 🚀 Quick Start Installation

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

### From Source (for development)
```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 test
make build
make install
````

### Verify:
```bash
grokkit version
```

## Configuration

### Environment Variables

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

```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](docs/developer-guide/CONFIGURATION.md) for advanced configuration options.


## 📖 Commands

See [The User Guide](docs/user-guide/index.md) 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](docs/user-guide/safety.md)


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

Common usage patterns to integrate Grokkit into your development cycle.

[Read the Workflows Guide](docs/user-guide/workflows.md)

## Shell Completions

Generate shell completions for faster command entry:

[Read the full Completion Guide](docs/user-guide/completion.md)

## 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)
- ✅ **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 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

Comprehensive build instructions, project structure details, and the Grokkit development workflow.

[Read the Development Overview Guide](docs/developer-guide/overview.md)

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

```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/developer-guide/TROUBLESHOOTING.md](docs/developer-guide/TROUBLESHOOTING.md) for more details.**

## License

[Unlicense](https://unlicense.org/) - Free for any use, no attribution required.

---

**Made with ❤️ using Grok AI**