vibe 🌊

Transform natural language into shell commands using AI. Works natively with OpenAI, Anthropic, Groq, OpenRouter, Ollama, LM Studio, and more.

# Type your intent in natural language
list all docker containers

# Press Ctrl+G

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

• 🧠 Natural language to commands - Just describe what you want
• 🖥️ OS-aware generation - Commands that work on YOUR system (macOS/Linux/Windows)
• ⚡ Lightning fast - Cached responses are 100-400x faster
• 🎬 Streaming output - Typewriter effect with progress indicators
• 🔌 Multi-provider - Native support for OpenAI, Anthropic, Groq, OpenRouter, Ollama, LM Studio, custom OpenAI-compatible gateways, and more
• 🛡️ Safe by default - Preview commands before execution
• 📚 Learn while you work - Inline explanations for every command
• 📜 Query history - Interactive menu to browse and re-run previous queries
• 🎯 Single binary - One compiled binary, no runtime dependencies to install

brew tap skymoore/tap
brew install --cask vibe-zsh

The Homebrew installation automatically:

• Installs vibe to ~/.oh-my-zsh/custom/plugins/vibe
• Adds vibe to your plugins list in ~/.zshrc
• Creates a global vibe-zsh command for CLI usage

After installation, reload your shell:

source ~/.zshrc

Note: Requires Oh-My-Zsh. If not installed, the installer will provide instructions.

For oh-my-zsh integration:

curl -fsSL https://raw.githubusercontent.com/skymoore/vibe-zsh/main/install.sh | bash

Or using wget:

wget -qO- https://raw.githubusercontent.com/skymoore/vibe-zsh/main/install.sh | bash

This script downloads the latest release and installs it to ~/.oh-my-zsh/custom/plugins/vibe. You'll need to manually add vibe to your plugins list in ~/.zshrc.

1. Clone the repository:

   git clone https://github.com/skymoore/vibe-zsh.git ~/.oh-my-zsh/custom/plugins/vibe

2. Build the binary:

   cd ~/.oh-my-zsh/custom/plugins/vibe
   make build

3. Add to your .zshrc:

   plugins=(... vibe)

4. Reload your shell:

   source ~/.zshrc

Add these to your ~/.zshrc (all optional).

vibe-zsh uses gollm to talk to each provider natively. There are three kinds of provider:

• Hosted providers (openai, anthropic, groq, openrouter, deepseek, google-openai, mistral, cohere) have a fixed endpoint built in. You only need to choose the provider, set VIBE_API_KEY, and pick a VIBE_MODEL — you do not set VIBE_API_URL.
• Local providers (ollama, lmstudio, vllm) run on your machine. Set VIBE_API_URL to point at the local server; no API key is required.
• Custom OpenAI-compatible gateways (openai-compatible) are OpenAI-compatible endpoints that you host or proxy yourself and that require a Bearer API key. Set both VIBE_API_URL and VIBE_API_KEY. See Custom OpenAI-compatible gateways.

Select a provider with VIBE_PROVIDER. If you don't set it, vibe infers the provider from VIBE_API_URL (e.g. an openrouter.ai or :11434 URL), which is mainly there to keep older configs working. Setting VIBE_PROVIDER explicitly is the recommended approach.

The default VIBE_MODEL is llama3:8b (chosen for the default Ollama setup). Always set VIBE_MODEL when you use a hosted provider, or requests will ask for a model that doesn't exist there.

export VIBE_PROVIDER="openai"
export VIBE_API_KEY="sk-..."
export VIBE_MODEL="gpt-4o"
# No VIBE_API_URL needed — the openai provider always targets api.openai.com.

export VIBE_PROVIDER="anthropic"
export VIBE_API_KEY="sk-ant-..."
export VIBE_MODEL="claude-3-5-sonnet-20241022"

export VIBE_PROVIDER="groq"
export VIBE_API_KEY="gsk_..."
export VIBE_MODEL="llama-3.1-70b-versatile"

export VIBE_PROVIDER="openrouter"
export VIBE_API_KEY="sk-or-..."
export VIBE_MODEL="anthropic/claude-3.5-sonnet"

export VIBE_PROVIDER="ollama"
export VIBE_API_URL="http://localhost:11434/v1"
export VIBE_MODEL="llama3:8b"
# Ollama must be running; no API key required.

export VIBE_PROVIDER="lmstudio"
export VIBE_API_URL="http://localhost:1234/v1"
export VIBE_MODEL="local-model"
# LM Studio must be running and reachable when vibe starts.

Many services (self-hosted gateways, proxies, alternative inference hosts) expose an OpenAI-compatible /v1 API but require a Bearer API key. The openai provider cannot reach these — it always points at api.openai.com and ignores VIBE_API_URL. The vllm provider honors a custom endpoint but sends no Authorization header, so authenticated gateways reject it with 401.

For these gateways, use the dedicated openai-compatible provider. It honors VIBE_API_URL and sends VIBE_API_KEY as a Bearer token:

export VIBE_PROVIDER="openai-compatible"   # custom endpoint + Bearer auth
export VIBE_API_URL="https://your-gateway.example.com/v1"
export VIBE_API_KEY="sk-..."               # sent as: Authorization: Bearer sk-...
export VIBE_MODEL="your-model-name"

Provider cheat sheet for OpenAI-compatible endpoints:

Worked example with a real-looking gateway:

# ❌ WRONG — no VIBE_PROVIDER, but this is a hosted-looking URL? No: it's custom.
#    Older vibe versions defaulted to `openai` and hit api.openai.com.
#    `vllm` would reach the gateway but be rejected with 401 (no auth header).

# ✅ CORRECT — openai-compatible reaches the gateway AND authenticates
export VIBE_PROVIDER="openai-compatible"
export VIBE_API_URL="https://api.example.dev/v1"
export VIBE_API_KEY="sk-..."
export VIBE_MODEL="some-model"

Note on validation: gollm checks your configuration when vibe starts. Hosted providers validate the API key format up front (for example, Anthropic keys must start with sk-ant-), and local providers must already be running and reachable. If a provider is misconfigured, vibe reports an actionable error on the first query rather than silently failing.

1. Type a natural language description in your terminal
2. Press Ctrl+G
3. Review the generated command (with explanations)
4. Press Enter to execute, or edit first

History Menu:

Access your query history in two ways:

1. Keybinding: Press Ctrl+X then H
2. Command: Type vh and press Enter

Both methods open an interactive menu where you can:

• Browse previous queries with arrow keys
• Search with / (filter mode)
• Press Enter to insert the generated command into your buffer
• Press G to regenerate a new command from the original query
• Press V to edit the original query in your buffer
• Press A or Home to jump to the first entry
• Press E or End to jump to the last entry
• Press Esc or Q to cancel

The selected command appears on your command line, ready to execute!

Quick Regenerate:

Press Ctrl+X then G to instantly regenerate a new command from your most recent query without opening the menu.

Note: Don't run vibe-zsh history or ./vibe history directly - use vh or the keybinding instead.

You can also use vibe directly from the command line:

# Homebrew installation
vibe-zsh "list all docker containers"

# Manual installation (Oh-My-Zsh plugin)
~/.oh-my-zsh/custom/plugins/vibe/vibe "list all docker containers"

CLI Flags:

vibe-zsh --help                    # Show all available flags
vibe-zsh --debug "query"           # Enable debug logging
vibe-zsh --temperature 0.1 "query" # Override temperature
vibe-zsh --interactive "query"     # Confirm before execution

History Commands:

vh                                 # Interactive menu (recommended)
vibe-zsh history list              # List history in plain text
vibe-zsh history clear             # Clear all history

# Note: Use 'vh' or Ctrl+X H for interactive menu
# Don't use 'vibe-zsh history' directly (it just outputs to stdout)

Query History:

# Open history menu with keybinding
Ctrl+X H

# Or use the command
vh

# List history in plain text
vibe-zsh history list

# Clear all history
vibe-zsh history clear

File Operations:

show me all hidden files including their sizes
# → ls -lah

Docker:

show logs of nginx container and follow them
# → docker logs -f nginx

Git:

show me commits from last week
# → git log --since="1 week ago"

Find & Search:

find all python files modified today
# → find . -name "*.py" -mtime 0

Tab Completion:

vibe <TAB><TAB>
# Shows common query suggestions

Hide Explanations:

export VIBE_SHOW_EXPLANATION=false

Interactive Mode (confirm before inserting):

export VIBE_INTERACTIVE=true

Disable Cache:

export VIBE_ENABLE_CACHE=false

Disable Auto-Updates:

export VIBE_AUTO_UPDATE=false

Customize History Keybinding:

export VIBE_HISTORY_KEY="^R"      # Use Ctrl+R for history menu
export VIBE_REGENERATE_KEY="^[r"  # Use Alt+R for quick regenerate
# Note: Avoid ^H (Ctrl+H) as it conflicts with Backspace

Disable History:

export VIBE_ENABLE_HISTORY=false

1. Capture - You type natural language and press Ctrl+G
2. Context - vibe detects your OS (macOS/Linux/Windows) and shell (zsh/bash/etc.)
3. Generate - vibe sends your query with system context to the configured LLM
4. Parse - Response is structured as command + explanations
5. Cache - Response is cached for 24 hours (configurable)
6. Stream - Command is streamed to your terminal with typewriter effect
7. Insert - Command appears in your buffer for review
8. Execute - You press Enter to run (or edit first)

vibe automatically detects your operating system and shell, ensuring generated commands work on your system:

• macOS: Uses BSD utilities (e.g., find without -printf, sed -i '')
• Linux: Uses GNU utilities (e.g., find -printf, sed -i)
• Shell-specific: Generates syntax appropriate for zsh, bash, etc.

This means you get commands that actually work on your system, not generic Linux commands that fail on macOS!

• First query: ~500ms-2s (depends on LLM)
• Cached query: ~5-10ms (100-400x faster!)
• Binary size: ~8MB
• Memory usage: <10MB

• ✅ Commands are never executed automatically
• ✅ Full preview before execution
• ✅ Edit commands before running
• ✅ Warnings for dangerous commands
• ✅ Optional interactive confirmation mode
• ✅ Local-first with Ollama (your data stays private)

vibe automatically checks for updates once a week in the background (zero impact on performance). When an update is available, you'll see a notification:

⚠️  vibe v1.2.4 available (current: v1.2.3)
   Run: vibe --update

Manual Commands:

vibe --version              # Show current version
vibe --update               # Download and install latest version

Configuration:

export VIBE_AUTO_UPDATE=false           # Disable auto-update checks
export VIBE_UPDATE_CHECK_INTERVAL=14d   # Check every 2 weeks instead

Security:

• All downloads are verified using SHA256 checksums
• Checksums are published with each release
• Original binary is backed up before replacement
• Safe atomic file replacement

The update check runs in a background process after each command, so it never slows down your workflow. Updates are never installed automatically - you always control when to update.

Command not working after install:

• Reload your shell: source ~/.zshrc
• Verify plugin is in list: echo $plugins
• Check binary exists: ls ~/.oh-my-zsh/custom/plugins/vibe/vibe

Slow responses:

• Enable caching: export VIBE_ENABLE_CACHE=true
• Use a faster model or local LLM
• Check your network connection

Bad command suggestions:

• Try a different/better model
• Make your query more specific
• Check model supports structured output

Corrupted or garbage output:

• vibe now automatically handles corrupted LLM responses with multi-layer parsing
• Enable debug logs to see what's happening: export VIBE_DEBUG_LOGS=true
• Check logs for raw responses and parsing attempts
• Try increasing retries: export VIBE_MAX_RETRIES=5

Parsing errors:

• Enable JSON extraction: export VIBE_ENABLE_JSON_EXTRACTION=true (default)
• Disable strict validation temporarily: export VIBE_STRICT_VALIDATION=false
• Check debug logs to see which parsing layer succeeded/failed
• Some models produce cleaner JSON with lower temperature: export VIBE_TEMPERATURE=0.3

Ctrl+G does nothing:

• Ensure plugin is loaded: which vibe (should show a function)
• Check no other plugin uses Ctrl+G
• Try rebinding: bindkey '^G' vibe

• Zsh with Oh-My-Zsh
• An LLM provider — hosted (OpenAI, Anthropic, Groq, OpenRouter, etc.), local (Ollama, LM Studio, vLLM), or any custom OpenAI-compatible gateway
• macOS or Linux

brew uninstall --cask vibe-zsh
brew untap skymoore/tap  # Optional: remove the tap

Then remove vibe from your plugins list in ~/.zshrc and reload:

source ~/.zshrc

curl -fsSL https://raw.githubusercontent.com/skymoore/vibe-zsh/main/uninstall.sh | bash

Or using wget:

wget -qO- https://raw.githubusercontent.com/skymoore/vibe-zsh/main/uninstall.sh | bash

Then remove vibe from your plugins list in ~/.zshrc and reload:

source ~/.zshrc

git clone https://github.com/skymoore/vibe-zsh.git
cd vibe-zsh
make build        # Build for current platform
make build-all    # Build for all platforms
make test         # Run tests
make install      # Install to oh-my-zsh

Contributions welcome! This project uses:

• Go 1.26+
• Standard zsh scripting
• gollm for native multi-provider LLM access

GPLv3 License - see LICENSE

Inspired by LoganPederson/vibe

Built for terminal productivity enthusiasts 🚀