grokkit/docs/CONFIGURATION.md

Configuration Guide

Advanced configuration options and use cases for Grokkit.

Table of Contents

• Configuration Priority
• Environment Variables
• Config File
• Configuration Examples
• Advanced Use Cases
• 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:

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

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

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

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

# Just the essentials
default_model = "grok-4"
temperature = 0.7

Create Config File

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

# ~/.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"

# Usage
grokkit chat -m dev                # Fast model
grokkit review --debug             # With detailed logs

Example 2: Production Environment

Reliable, balanced settings.

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

# ~/.config/grokkit/config-creative.toml
default_model = "grok-4"
temperature = 0.9                  # More creative
timeout = 90

log_level = "info"

[aliases]
creative = "grok-4"

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

# 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

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

# ~/.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"

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

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

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

[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

# Manually specify when calling
grokkit chat -m chat
grokkit edit file.go "task" -m edit

Custom History Location

Useful for separating concerns or compliance:

[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:

timeout = 300                      # 5 minutes for slow connections

Or use proxy settings:

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:

# config.toml
api_key = "sk-123..."  # ❌ DON'T put in config file

✅ Do:

# 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

[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

# 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

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

# 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

# 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

# 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

# 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
• Architecture Overview