Configuration Reference

Complete reference for all vibe configuration options.

Environment Variables

All configuration is done through environment variables in your ~/.zshrc.

API Configuration

VIBE_API_URL

Type: String
Default: http://localhost:11434/v1
Description: The base URL for the OpenAI-compatible API endpoint.

Examples:

# Ollama (local)
export VIBE_API_URL="http://localhost:11434/v1"

# OpenAI
export VIBE_API_URL="https://api.openai.com/v1"

# Anthropic via OpenRouter
export VIBE_API_URL="https://openrouter.ai/api/v1"

# LM Studio
export VIBE_API_URL="http://localhost:1234/v1"

# Groq
export VIBE_API_URL="https://api.groq.com/openai/v1"

VIBE_API_KEY

Type: String
Default: "" (empty, not required for Ollama)
Description: API key for authentication. Required for most cloud providers.

Examples:

# OpenAI
export VIBE_API_KEY="sk-..."

# OpenRouter
export VIBE_API_KEY="sk-or-..."

# Groq
export VIBE_API_KEY="gsk_..."

Security Note: Never commit API keys to version control.

VIBE_MODEL

Type: String
Default: llama3:8b
Description: The model identifier to use for command generation.

Examples:

# Ollama
export VIBE_MODEL="llama3:8b"
export VIBE_MODEL="llama3.1:70b"
export VIBE_MODEL="codellama:13b"

# OpenAI
export VIBE_MODEL="gpt-4"
export VIBE_MODEL="gpt-4-turbo"
export VIBE_MODEL="gpt-3.5-turbo"

# Anthropic (via OpenRouter)
export VIBE_MODEL="anthropic/claude-3.5-sonnet"
export VIBE_MODEL="anthropic/claude-3-opus"

# Groq
export VIBE_MODEL="llama-3.1-70b-versatile"
export VIBE_MODEL="mixtral-8x7b-32768"

VIBE_TEMPERATURE

Type: Float
Default: 0.2
Range: 0.0 to 2.0
Description: Controls randomness in the model’s output. Lower values make output more deterministic, higher values more creative.

Examples:

# Most deterministic (default, recommended for commands)
export VIBE_TEMPERATURE=0.2

# More creative
export VIBE_TEMPERATURE=0.5

# Higher variation
export VIBE_TEMPERATURE=0.7

Recommendations:

• 0.0-0.3: Most consistent, predictable commands (recommended)
• 0.4-0.7: Balanced creativity and consistency
• 0.8-2.0: More variation (may produce unexpected results)

VIBE_MAX_TOKENS

Type: Integer
Default: 500
Description: Maximum number of tokens in the API response.

Examples:

# Shorter responses (faster)
export VIBE_MAX_TOKENS=300

# Default
export VIBE_MAX_TOKENS=500

# Longer responses (for complex commands)
export VIBE_MAX_TOKENS=1000

Note: Higher values increase API costs and response time.

VIBE_TIMEOUT

Type: Duration
Default: 30s
Description: Maximum time to wait for API response.

Examples:

# Shorter timeout
export VIBE_TIMEOUT=15s

# Default
export VIBE_TIMEOUT=30s

# Longer timeout (slow connections)
export VIBE_TIMEOUT=60s

Format: Number + unit (s for seconds, m for minutes)

Display Configuration

VIBE_SHOW_EXPLANATION

Type: Boolean
Default: true
Description: Show inline explanations for generated commands.

Examples:

# Show explanations (default)
export VIBE_SHOW_EXPLANATION=true

# Hide explanations
export VIBE_SHOW_EXPLANATION=false

When enabled:

docker ps -a
# docker: Docker command-line tool
# ps: List containers
# -a: Show all containers (not just running)

When disabled:

docker ps -a

VIBE_SHOW_WARNINGS

Type: Boolean
Default: true
Description: Display warnings for potentially dangerous commands.

Examples:

# Show warnings (default)
export VIBE_SHOW_WARNINGS=true

# Hide warnings
export VIBE_SHOW_WARNINGS=false

When enabled:

⚠️  WARNING: This command may delete files
rm -rf *

VIBE_PROGRESS_STYLE

Type: String
Default: dots
Description: The visual style of the progress spinner shown during command generation.

Examples:

# Dots (default)
export VIBE_PROGRESS_STYLE=dots

# Line
export VIBE_PROGRESS_STYLE=line

# Circle
export VIBE_PROGRESS_STYLE=circle

# Bounce
export VIBE_PROGRESS_STYLE=bounce

# Arrow
export VIBE_PROGRESS_STYLE=arrow

# Runes
export VIBE_PROGRESS_STYLE=runes

Available Styles:

• dots - Braille dot animation (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
• line - Classic line spinner (- \ | /)
• circle - Rotating circle (◐ ◓ ◑ ◒)
• bounce - Bouncing dots (⠁ ⠂ ⠄ ⠂)
• arrow - Rotating arrow (← ↖ ↑ ↗ → ↘ ↓ ↙)
• runes - Norse runes (ᛜ ᛃ ᛋ)

Note: The spinner is only shown when VIBE_SHOW_PROGRESS=true (default).

Behavior Configuration

VIBE_INTERACTIVE

Type: Boolean
Default: false
Description: Require confirmation before inserting commands into the prompt.

Examples:

# Auto-insert (default)
export VIBE_INTERACTIVE=false

# Require confirmation
export VIBE_INTERACTIVE=true

When enabled:

---
docker ps -a
---
Execute this command? [Y/n]

Parsing & Reliability Configuration

VIBE_USE_STRUCTURED_OUTPUT

Type: Boolean
Default: true
Description: Use JSON schema for structured responses. Provides better reliability with models that support structured output.

Examples:

# Use structured output (default, recommended)
export VIBE_USE_STRUCTURED_OUTPUT=true

# Disable structured output (fallback to text parsing)
export VIBE_USE_STRUCTURED_OUTPUT=false

Recommendations:

• Keep enabled for OpenAI, Claude, and modern models
• Disable if your model doesn’t support JSON schema

VIBE_MAX_RETRIES

Type: Integer
Default: 3
Description: Maximum retry attempts for failed parsing. Higher values increase reliability but may slow down error cases.

Examples:

# Conservative (faster failures)
export VIBE_MAX_RETRIES=2

# Default (recommended)
export VIBE_MAX_RETRIES=3

# Aggressive (maximum reliability)
export VIBE_MAX_RETRIES=5

When to adjust:

• Increase if you see occasional parsing failures
• Decrease if you want faster error responses

VIBE_ENABLE_JSON_EXTRACTION

Type: Boolean
Default: true
Description: Automatically extract valid JSON from corrupted LLM responses containing garbage characters, escape sequences, or Unicode pollution.

Examples:

# Enable JSON extraction (default, recommended)
export VIBE_ENABLE_JSON_EXTRACTION=true

# Disable extraction (strict parsing only)
export VIBE_ENABLE_JSON_EXTRACTION=false

What it handles:

• Terminal escape sequences (\x1b[200~, \x1b[201~)
• Unicode separators (\u2028, \u2029)
• Control characters and garbage text
• JSON buried in explanatory text

VIBE_STRICT_VALIDATION

Type: Boolean
Default: true
Description: Validate response structure for required fields and proper formatting.

Examples:

# Enable validation (default, recommended)
export VIBE_STRICT_VALIDATION=true

# Disable validation (permissive)
export VIBE_STRICT_VALIDATION=false

What it checks:

• Command field is non-empty
• Explanation array has entries
• No whitespace-only fields

When to disable:

• Debugging parsing issues
• Testing with experimental models

VIBE_DEBUG_LOGS

Type: Boolean
Default: false
Description: Enable detailed debug logging for troubleshooting parsing and API issues.

Examples:

# Disable debug logs (default)
export VIBE_DEBUG_LOGS=false

# Enable debug logs
export VIBE_DEBUG_LOGS=true

What it logs:

• Raw LLM responses (first 500 chars)
• Parsing attempts and failures
• Which fallback layer succeeded
• JSON extraction details
• Garbage removed from responses

Output example:

[VIBE] [ATTEMPT 1][structured_output] Parsing failed: invalid JSON
[VIBE] [ATTEMPT 2][enhanced_parsing] Parsing failed: ...
[VIBE] [JSON_EXTRACT] Success
Trimmed prefix: "AWS\x1b[200~..."
[VIBE] [SUCCESS] Layer 'enhanced_parsing' succeeded on attempt 2

VIBE_SHOW_RETRY_STATUS

Type: Boolean
Default: true
Description: Show progress indicator during retry attempts.

Examples:

# Show retry status (default)
export VIBE_SHOW_RETRY_STATUS=true

# Hide retry status
export VIBE_SHOW_RETRY_STATUS=false

When enabled:

⏳ Generating command (attempt 2/3)...

History Configuration

VIBE_ENABLE_HISTORY

Type: Boolean
Default: true
Description: Enable automatic tracking of query history.

Examples:

# Enable history (default)
export VIBE_ENABLE_HISTORY=true

# Disable history
export VIBE_ENABLE_HISTORY=false

When enabled:

• Queries and generated commands are saved to ~/.cache/vibe/history.json
• Access history via vh command or Ctrl+X H keybinding
• History persists across terminal sessions

VIBE_HISTORY_SIZE

Type: Integer
Default: 100
Description: Maximum number of history entries to keep. Older entries are automatically removed when limit is reached.

Examples:

# Default (100 entries)
export VIBE_HISTORY_SIZE=100

# More history
export VIBE_HISTORY_SIZE=200

# Less history (faster loading)
export VIBE_HISTORY_SIZE=50

Storage: Each entry is ~100-200 bytes, so 100 entries ≈ 10-20KB

VIBE_HISTORY_KEY

Type: String
Default: ^Xh (Ctrl+X H)
Description: Keybinding to open the interactive history menu.

Examples:

# Default (Ctrl+X H)
export VIBE_HISTORY_KEY="^Xh"

# Use Ctrl+R instead
export VIBE_HISTORY_KEY="^R"

# Use Ctrl+X followed by Ctrl+H
export VIBE_HISTORY_KEY="^X^H"

Format: ZSH keybinding notation

• ^X = Ctrl+X
• ^R = Ctrl+R
• ^[h = Alt+H (may not work on all systems)

Warning: Avoid ^H (Ctrl+H) as it conflicts with Backspace.

History Access Methods:

1. Keybinding: Press the configured key combination
2. Command: Type vh and press Enter

Both methods open the same interactive menu and insert the selected command into your buffer.

VIBE_REGENERATE_KEY

Type: String
Default: ^Xg (Ctrl+X G)
Description: Keybinding to instantly regenerate a new command from the most recent query without opening the history menu.

Examples:

# Default (Ctrl+X G)
export VIBE_REGENERATE_KEY="^Xg"

# Use Alt+R instead
export VIBE_REGENERATE_KEY="^[r"

# Use Ctrl+R (if not using for history)
export VIBE_REGENERATE_KEY="^R"

Format: ZSH keybinding notation

• ^Xg = Ctrl+X followed by G
• ^[r = Alt+R
• ^R = Ctrl+R

Warning: Avoid ^H (Ctrl+H) as it conflicts with Backspace.

Use Case: Quickly try a different variation of your last command without navigating through the history menu.

Cache Configuration

VIBE_ENABLE_CACHE

Type: Boolean
Default: true
Description: Enable response caching for faster repeated queries.

Examples:

# Enable cache (default)
export VIBE_ENABLE_CACHE=true

# Disable cache
export VIBE_ENABLE_CACHE=false

Impact:

• Enabled: Cached queries return in ~5-10ms (100-400x faster)
• Disabled: Every query hits the API

VIBE_CACHE_TTL

Type: Duration
Default: 24h
Description: How long cached responses remain valid.

Examples:

# 1 hour
export VIBE_CACHE_TTL=1h

# 12 hours
export VIBE_CACHE_TTL=12h

# 24 hours (default)
export VIBE_CACHE_TTL=24h

# 7 days
export VIBE_CACHE_TTL=168h

Format: Number + unit (h for hours, m for minutes)

Cache location: ~/.cache/vibe/

Configuration Templates

Local LLM (Ollama)

# Minimal configuration (uses defaults)
export VIBE_API_URL="http://localhost:11434/v1"
export VIBE_MODEL="llama3:8b"

OpenAI

export VIBE_API_URL="https://api.openai.com/v1"
export VIBE_API_KEY="sk-..."
export VIBE_MODEL="gpt-4"
export VIBE_TEMPERATURE=0.2
export VIBE_TIMEOUT=30s

Anthropic (via OpenRouter)

export VIBE_API_URL="https://openrouter.ai/api/v1"
export VIBE_API_KEY="sk-or-..."
export VIBE_MODEL="anthropic/claude-3.5-sonnet"
export VIBE_TEMPERATURE=0.2
export VIBE_MAX_TOKENS=500

Groq

export VIBE_API_URL="https://api.groq.com/openai/v1"
export VIBE_API_KEY="gsk_..."
export VIBE_MODEL="llama-3.1-70b-versatile"
export VIBE_TEMPERATURE=0.4

Complete Configuration Example

# API Configuration
export VIBE_API_URL="https://api.openai.com/v1"
export VIBE_API_KEY="sk-..."
export VIBE_MODEL="gpt-4"
export VIBE_TEMPERATURE=0.2
export VIBE_MAX_TOKENS=500
export VIBE_TIMEOUT=30s

# Parsing & Reliability (defaults shown, usually don't need to change)
export VIBE_USE_STRUCTURED_OUTPUT=true
export VIBE_MAX_RETRIES=3
export VIBE_ENABLE_JSON_EXTRACTION=true
export VIBE_STRICT_VALIDATION=true
export VIBE_DEBUG_LOGS=false
export VIBE_SHOW_RETRY_STATUS=true

# Display Configuration
export VIBE_SHOW_EXPLANATION=true
export VIBE_SHOW_WARNINGS=true

# Behavior Configuration
export VIBE_INTERACTIVE=false

# History Configuration
export VIBE_ENABLE_HISTORY=true
export VIBE_HISTORY_SIZE=100
export VIBE_HISTORY_KEY="^Xh"
export VIBE_REGENERATE_KEY="^Xg"

# Cache Configuration
export VIBE_ENABLE_CACHE=true
export VIBE_CACHE_TTL=24h

Debugging Configuration

When troubleshooting issues, use this minimal debug config:

# Enable debug logging
export VIBE_DEBUG_LOGS=true

# Increase retries to see all fallback attempts
export VIBE_MAX_RETRIES=5

# Keep other settings at defaults
export VIBE_ENABLE_JSON_EXTRACTION=true
export VIBE_STRICT_VALIDATION=true
export VIBE_SHOW_RETRY_STATUS=true

Plugin Configuration

VIBE_PLUGIN_DIR

Type: String (read-only)
Default: Auto-detected
Description: Directory where the vibe plugin is installed. Automatically set by the plugin.

# Typically:
~/.oh-my-zsh/custom/plugins/vibe

VIBE_BINARY

Type: String
Default: ${VIBE_PLUGIN_DIR}/vibe
Description: Path to the vibe binary. Override if you want to use a custom binary location.

Example:

export VIBE_BINARY="/usr/local/bin/vibe"

Quick Reference Table

Core Settings

Parsing & Reliability

Display & Behavior

History Settings

Cache Settings

System

Applying Configuration Changes

After modifying environment variables in ~/.zshrc:

source ~/.zshrc

Or restart your terminal.

Configuration Files

vibe uses environment variables only - no configuration files are required or used.

Cache location:

~/.cache/vibe/

History location:

~/.cache/vibe/history.json

Plugin location:

~/.oh-my-zsh/custom/plugins/vibe/

To reset cache:

rm -rf ~/.cache/vibe/*

To clear history:

vibe-zsh history clear
# or manually:
rm ~/.cache/vibe/history.json

Troubleshooting Configuration

View Current Configuration

Check what vibe sees:

env | grep VIBE_

Test Configuration

Test with a simple query:

~/.oh-my-zsh/custom/plugins/vibe/vibe "list files"

Common Issues

“Connection refused”

• Check VIBE_API_URL is correct
• Verify service is running (e.g., ollama serve)

“Unauthorized” or “Invalid API key”

• Verify VIBE_API_KEY is set and correct
• Check for extra quotes or spaces

“Model not found”

• Verify VIBE_MODEL exists for your provider
• For Ollama: ollama list

Slow responses

• Enable cache: VIBE_ENABLE_CACHE=true
• Reduce VIBE_MAX_TOKENS
• Use faster model or local LLM

Parsing failures or corrupted output

• Enable debug logs: VIBE_DEBUG_LOGS=true
• Check logs for which layer is failing
• Ensure JSON extraction is enabled: VIBE_ENABLE_JSON_EXTRACTION=true
• Try lowering temperature: VIBE_TEMPERATURE=0.3
• Increase retries: VIBE_MAX_RETRIES=5