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-54%25-orange)]()
[![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

### One-line Install (Recommended)

**Bash (Linux/macOS):**
```bash
export VERSION=0.3.9
curl -fsSL https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh | bash -s -- --verify
```

**PowerShell (Windows):**
```pwsh
$env:VERSION="0.3.9"
 irm https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v$env:VERSION/grokkit-install.ps1 | iex
```

Both installers feature:
- ✅ **Automatic platform detection** (Linux, macOS, Windows)
- ✅ **SHA256 checksum verification**
- ✅ **Safe extraction to `~/.local/bin` or `$env:LOCALAPPDATA\bin`**
- ✅ **No temporary files left behind**

### Download First Approach

**Bash (Linux/macOS):**

```bash
export VERSION=0.3.9
curl -fsSL https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh -o grokkit-install.sh
bash grokkit-install.sh --verify
```

**PowerShell (Windows):**

```pwsh
$env:VERSION="0.3.9"
 irm https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v$env:VERSION/grokkit-install.ps1 -OutFile grokkit-install.ps1
 .\grokkit-install.ps1 -Verify
```

> **💡 Windows Note**: PowerShell installers auto-detect Windows architecture (x86_64, ARM64) and place the binary in `%LOCALAPPDATA%\bin\grokkit.exe`. Add this path to your PATH if not already present.

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


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

#### 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 54%+** - Comprehensive unit tests including all command message builders
- ✅ **Coverage gate in CI** - Builds fail if coverage drops below 50%
- ✅ **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:**

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