Greg Gauthier
cbd779c882
Add comprehensive documentation files: - ARCHITECTURE.md: System design overview - CONFIGURATION.md: Advanced config guide - TROUBLESHOOTING.md: Common issues and solutions Update README with: - Badges for coverage, Go version, license - Expanded commands, workflows, features sections - Improved quick start and logging examples
486 lines
10 KiB
Markdown
486 lines
10 KiB
Markdown
# Configuration Guide
|
|
|
|
Advanced configuration options and use cases for Grokkit.
|
|
|
|
## Table of Contents
|
|
|
|
- [Configuration Priority](#configuration-priority)
|
|
- [Environment Variables](#environment-variables)
|
|
- [Config File](#config-file)
|
|
- [Configuration Examples](#configuration-examples)
|
|
- [Advanced Use Cases](#advanced-use-cases)
|
|
- [Best Practices](#best-practices)
|
|
|
|
## Configuration Priority
|
|
|
|
Grokkit resolves configuration in this order (highest to lowest):
|
|
|
|
1. **CLI Flags** - `grokkit chat --model grok-4`
|
|
2. **Environment Variables** - `export XAI_API_KEY=...`
|
|
3. **Config File** - `~/.config/grokkit/config.toml`
|
|
4. **Defaults** - Hardcoded in application
|
|
|
|
**Example:**
|
|
```bash
|
|
# Config file says: default_model = "grok-4"
|
|
# Command uses:
|
|
grokkit chat -m grok-beta
|
|
|
|
# Result: Uses grok-beta (CLI flag wins)
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### XAI_API_KEY (Required)
|
|
|
|
Your xAI API key.
|
|
|
|
```bash
|
|
# Set for current session
|
|
export XAI_API_KEY=sk-your-key-here
|
|
|
|
# Set permanently (bash)
|
|
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
|
|
# Set permanently (zsh)
|
|
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.zshrc
|
|
source ~/.zshrc
|
|
|
|
# Verify (safely)
|
|
echo $XAI_API_KEY | sed 's/sk-.*$/sk-***/'
|
|
```
|
|
|
|
### Environment-based Config
|
|
|
|
You can also set config values via environment:
|
|
|
|
```bash
|
|
export GROKKIT_MODEL=grok-4
|
|
export GROKKIT_TEMPERATURE=0.8
|
|
export GROKKIT_LOG_LEVEL=debug
|
|
```
|
|
|
|
Viper (the config library) automatically reads these with `AutomaticEnv()`.
|
|
|
|
## Config File
|
|
|
|
### Location
|
|
|
|
Default location: `~/.config/grokkit/config.toml`
|
|
|
|
Custom location via Viper (not currently exposed, but easy to add).
|
|
|
|
### Full Configuration
|
|
|
|
```toml
|
|
# ~/.config/grokkit/config.toml
|
|
|
|
# ===== Model Settings =====
|
|
default_model = "grok-4" # Model to use by default
|
|
temperature = 0.7 # Creativity (0.0 = deterministic, 1.0 = creative)
|
|
timeout = 60 # API timeout in seconds
|
|
|
|
# ===== Logging Settings =====
|
|
log_level = "info" # debug | info | warn | error
|
|
|
|
# ===== Model Aliases =====
|
|
# Create shortcuts for frequently used models
|
|
[aliases]
|
|
beta = "grok-beta-2" # grokkit chat -m beta
|
|
fast = "grok-4-mini" # grokkit chat -m fast
|
|
creative = "grok-4" # grokkit chat -m creative
|
|
|
|
# ===== Chat Settings =====
|
|
[chat]
|
|
history_file = "~/.config/grokkit/chat_history.json" # Custom history location
|
|
# max_history = 100 # Future: Limit history size
|
|
```
|
|
|
|
### Minimal Configuration
|
|
|
|
```toml
|
|
# Just the essentials
|
|
default_model = "grok-4"
|
|
temperature = 0.7
|
|
```
|
|
|
|
### Create Config File
|
|
|
|
```bash
|
|
# Create directory
|
|
mkdir -p ~/.config/grokkit
|
|
|
|
# Create config with defaults
|
|
cat > ~/.config/grokkit/config.toml <<'EOF'
|
|
default_model = "grok-4"
|
|
temperature = 0.7
|
|
timeout = 60
|
|
log_level = "info"
|
|
|
|
[aliases]
|
|
beta = "grok-beta-2"
|
|
fast = "grok-4-mini"
|
|
|
|
[chat]
|
|
history_file = "~/.config/grokkit/chat_history.json"
|
|
EOF
|
|
|
|
# Verify
|
|
cat ~/.config/grokkit/config.toml
|
|
```
|
|
|
|
## Configuration Examples
|
|
|
|
### Example 1: Development Environment
|
|
|
|
Fast iteration, detailed logs, shorter timeouts.
|
|
|
|
```toml
|
|
# ~/.config/grokkit/config.toml
|
|
default_model = "grok-4-mini" # Fast model for quick iterations
|
|
temperature = 0.5 # More predictable responses
|
|
timeout = 30 # Fail fast
|
|
log_level = "debug" # Detailed logging
|
|
|
|
[aliases]
|
|
dev = "grok-4-mini"
|
|
prod = "grok-4"
|
|
```
|
|
|
|
```bash
|
|
# Usage
|
|
grokkit chat -m dev # Fast model
|
|
grokkit review --debug # With detailed logs
|
|
```
|
|
|
|
### Example 2: Production Environment
|
|
|
|
Reliable, balanced settings.
|
|
|
|
```toml
|
|
# ~/.config/grokkit/config.toml
|
|
default_model = "grok-4"
|
|
temperature = 0.7
|
|
timeout = 120 # Longer timeout for reliability
|
|
log_level = "warn" # Only warnings and errors
|
|
|
|
[aliases]
|
|
prod = "grok-4"
|
|
fast = "grok-4-mini"
|
|
```
|
|
|
|
### Example 3: Creative Writing
|
|
|
|
Higher temperature for more creative responses.
|
|
|
|
```toml
|
|
# ~/.config/grokkit/config-creative.toml
|
|
default_model = "grok-4"
|
|
temperature = 0.9 # More creative
|
|
timeout = 90
|
|
|
|
log_level = "info"
|
|
|
|
[aliases]
|
|
creative = "grok-4"
|
|
```
|
|
|
|
```bash
|
|
# Use with environment variable pointing to alt config
|
|
# (requires code modification to support)
|
|
grokkit chat # Uses high creativity settings
|
|
```
|
|
|
|
### Example 4: Team Settings
|
|
|
|
Standardized settings for team consistency.
|
|
|
|
```toml
|
|
# team-shared-config.toml
|
|
default_model = "grok-4"
|
|
temperature = 0.7
|
|
timeout = 60
|
|
log_level = "info"
|
|
|
|
[aliases]
|
|
review = "grok-4" # For code reviews
|
|
commit = "grok-4-mini" # For commit messages
|
|
docs = "grok-4" # For documentation
|
|
|
|
[chat]
|
|
# Don't save history in team environment
|
|
# (requires code modification)
|
|
save_history = false
|
|
```
|
|
|
|
```bash
|
|
# Usage
|
|
grokkit review -m review # Explicit model for reviews
|
|
grokkit commit -m commit # Fast model for commits
|
|
```
|
|
|
|
### Example 5: Cost Optimization
|
|
|
|
Minimize API costs while maintaining functionality.
|
|
|
|
```toml
|
|
# ~/.config/grokkit/config.toml
|
|
default_model = "grok-4-mini" # Cheaper model
|
|
temperature = 0.5 # More deterministic = fewer tokens
|
|
timeout = 45
|
|
|
|
[aliases]
|
|
cheap = "grok-4-mini"
|
|
expensive = "grok-4"
|
|
```
|
|
|
|
```bash
|
|
# Use cheap model by default
|
|
grokkit chat
|
|
|
|
# Use expensive model only when needed
|
|
grokkit edit complex.go "major refactor" -m expensive
|
|
```
|
|
|
|
## Advanced Use Cases
|
|
|
|
### Multiple Profiles
|
|
|
|
Create different config files for different use cases.
|
|
|
|
```bash
|
|
# Directory structure
|
|
~/.config/grokkit/
|
|
├── config.toml # Default
|
|
├── config-dev.toml # Development
|
|
├── config-creative.toml # Creative work
|
|
└── config-production.toml # Production use
|
|
|
|
# Symlink to switch profiles
|
|
ln -sf ~/.config/grokkit/config-dev.toml ~/.config/grokkit/config.toml
|
|
```
|
|
|
|
### Project-specific Settings
|
|
|
|
Place `.env` file in project root:
|
|
|
|
```bash
|
|
# /path/to/project/.env
|
|
export XAI_API_KEY=sk-project-specific-key
|
|
export GROKKIT_MODEL=grok-4-mini
|
|
export GROKKIT_LOG_LEVEL=debug
|
|
|
|
# Load in shell
|
|
source .env
|
|
grokkit chat # Uses project settings
|
|
```
|
|
|
|
### Per-command Defaults
|
|
|
|
Use aliases for command-specific models:
|
|
|
|
```toml
|
|
[aliases]
|
|
chat = "grok-4" # Best quality for chat
|
|
edit = "grok-4" # Precision for edits
|
|
review = "grok-4" # Thorough reviews
|
|
commit = "grok-4-mini" # Fast for simple commits
|
|
history = "grok-4-mini" # Fast summaries
|
|
```
|
|
|
|
```bash
|
|
# Manually specify when calling
|
|
grokkit chat -m chat
|
|
grokkit edit file.go "task" -m edit
|
|
```
|
|
|
|
### Custom History Location
|
|
|
|
Useful for separating concerns or compliance:
|
|
|
|
```toml
|
|
[chat]
|
|
# Separate histories per project
|
|
history_file = "~/projects/current/.grokkit-history.json"
|
|
|
|
# Or don't save history at all
|
|
history_file = "/dev/null"
|
|
```
|
|
|
|
### Network-restricted Environments
|
|
|
|
Adjust timeouts for slow networks:
|
|
|
|
```toml
|
|
timeout = 300 # 5 minutes for slow connections
|
|
```
|
|
|
|
Or use proxy settings:
|
|
|
|
```bash
|
|
export HTTP_PROXY=http://proxy.corp.com:8080
|
|
export HTTPS_PROXY=http://proxy.corp.com:8080
|
|
grokkit chat
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Keep API Keys Secure
|
|
|
|
**❌ Don't:**
|
|
```toml
|
|
# config.toml
|
|
api_key = "sk-123..." # ❌ DON'T put in config file
|
|
```
|
|
|
|
**✅ Do:**
|
|
```bash
|
|
# Use environment variables
|
|
export XAI_API_KEY=sk-...
|
|
|
|
# Or use a secrets manager
|
|
export XAI_API_KEY=$(vault kv get -field=key secret/grokkit)
|
|
```
|
|
|
|
### 2. Use Aliases for Workflows
|
|
|
|
```toml
|
|
[aliases]
|
|
# Descriptive names
|
|
review-critical = "grok-4" # Thorough for critical code
|
|
review-routine = "grok-4-mini" # Fast for routine changes
|
|
refactor = "grok-4" # Best model for complex refactoring
|
|
```
|
|
|
|
### 3. Adjust Temperature by Use Case
|
|
|
|
| Use Case | Temperature | Reason |
|
|
|----------|-------------|--------|
|
|
| Code generation | 0.3 - 0.5 | Predictable, correct code |
|
|
| Code review | 0.5 - 0.7 | Balanced analysis |
|
|
| Commit messages | 0.5 | Consistent format |
|
|
| Documentation | 0.7 | Clear but varied language |
|
|
| Creative writing | 0.8 - 1.0 | More variety |
|
|
| Debugging | 0.3 | Precise analysis |
|
|
|
|
### 4. Manage Log Levels
|
|
|
|
| Environment | Log Level | Reason |
|
|
|-------------|-----------|--------|
|
|
| Development | `debug` | See everything |
|
|
| Staging | `info` | Track operations |
|
|
| Production | `warn` | Errors and warnings only |
|
|
| CI/CD | `error` | Failures only |
|
|
|
|
### 5. Set Appropriate Timeouts
|
|
|
|
| Network | Timeout | Reason |
|
|
|---------|---------|--------|
|
|
| Fast (LAN) | 30s | Fail fast |
|
|
| Normal (broadband) | 60s | Balanced |
|
|
| Slow (mobile/VPN) | 120s | Allow completion |
|
|
| Restricted (corporate) | 180s | Account for proxies |
|
|
|
|
### 6. Version Control Config
|
|
|
|
```bash
|
|
# Add template to repo (without secrets)
|
|
cat > .grokkit-config.template.toml <<'EOF'
|
|
default_model = "grok-4"
|
|
temperature = 0.7
|
|
timeout = 60
|
|
log_level = "info"
|
|
|
|
[aliases]
|
|
dev = "grok-4-mini"
|
|
prod = "grok-4"
|
|
EOF
|
|
|
|
# .gitignore
|
|
echo "config.toml" >> .gitignore # Don't commit actual config
|
|
```
|
|
|
|
### 7. Document Team Conventions
|
|
|
|
```toml
|
|
# team-config.toml - Team standard configuration
|
|
# Copy this file to ~/.config/grokkit/config.toml
|
|
|
|
default_model = "grok-4"
|
|
temperature = 0.7 # Don't change without team discussion
|
|
|
|
[aliases]
|
|
# Use these for consistency
|
|
code-review = "grok-4"
|
|
quick-commit = "grok-4-mini"
|
|
```
|
|
|
|
## Configuration Schema
|
|
|
|
Reference for all available options:
|
|
|
|
```toml
|
|
# String: Model identifier
|
|
default_model = "grok-4"
|
|
|
|
# Float: 0.0-1.0 (creativity)
|
|
temperature = 0.7
|
|
|
|
# Integer: Seconds (API timeout)
|
|
timeout = 60
|
|
|
|
# String: "debug" | "info" | "warn" | "error"
|
|
log_level = "info"
|
|
|
|
# Map of string to string
|
|
[aliases]
|
|
alias_name = "actual-model-name"
|
|
|
|
# Chat-specific settings
|
|
[chat]
|
|
history_file = "/path/to/history.json"
|
|
```
|
|
|
|
## Troubleshooting Config
|
|
|
|
### Check Current Config
|
|
|
|
```bash
|
|
# View config file
|
|
cat ~/.config/grokkit/config.toml
|
|
|
|
# Test with debug mode (shows resolved config)
|
|
grokkit chat --debug 2>&1 | head -20
|
|
```
|
|
|
|
### Validate TOML Syntax
|
|
|
|
```bash
|
|
# Online validator
|
|
# https://www.toml-lint.com/
|
|
|
|
# Or install tomll
|
|
go install github.com/pelletier/go-toml/v2/cmd/tomll@latest
|
|
tomll ~/.config/grokkit/config.toml
|
|
```
|
|
|
|
### Reset to Defaults
|
|
|
|
```bash
|
|
# Backup current config
|
|
mv ~/.config/grokkit/config.toml ~/.config/grokkit/config.toml.backup
|
|
|
|
# App will use defaults
|
|
grokkit chat
|
|
|
|
# Restore if needed
|
|
mv ~/.config/grokkit/config.toml.backup ~/.config/grokkit/config.toml
|
|
```
|
|
|
|
---
|
|
|
|
**See also:**
|
|
- [Troubleshooting Guide](TROUBLESHOOTING.md)
|
|
- [Architecture Overview](ARCHITECTURE.md)
|