Greg Gauthier
cd47686679
- Simplified README.md by moving detailed command docs, workflows, and development info to dedicated user-guide/ and developer-guide/ directories. - Created index.md files for both guides to improve navigation. - Extracted individual command guides (e.g., chat.md, edit.md) into user-guide/ for focused, maintainable documentation. - Moved architecture, configuration, and troubleshooting to developer-guide/. - Updated README links to point to the new docs structure.
222 lines
6.1 KiB
Markdown
222 lines
6.1 KiB
Markdown
# Grokkit
|
|
|
|
Grokkit is a fast Go CLI integrating Grok AI with git workflows and general chat/edit functionality.
|
|
|
|
|
|
[]()
|
|
[]()
|
|
[]()
|
|
|
|
## 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**
|