🤖 AI-powered command suggestions and explanations for Zsh using Claude AI. Get intelligent shell command help with simple keybindings.

Transform natural language into executable shell commands, or get detailed explanations of complex commands - all directly in your terminal with Claude AI integration.

• 🧠 Smart Suggestions: Type natural language, get executable commands
• 📖 Command Explanations: Understand what complex commands do
• ⚡ Interactive: Simple keybindings for instant access
• 🔒 Standalone: No GitHub CLI dependencies required
• 🎯 Multiple AI Models: Choose from Claude 3.5 Haiku to Opus 4.1
• 🔧 Easy Setup: One-command configuration
• 📦 Plugin Manager Support: Works with oh-my-zsh, zinit, antigen, zplug

1. Claude API Key: Get one from console.anthropic.com/settings/keys
2. curl: For API requests (usually pre-installed)
3. jq: For JSON parsing

   # macOS
   brew install jq
   
   # Ubuntu/Debian
   sudo apt install jq
   
   # CentOS/RHEL
   sudo yum install jq

# Clone the plugin
git clone https://github.com/HundredAcreStudio/zsh-claude ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-claude

# Add to your ~/.zshrc plugins list
plugins=(... zsh-claude)

# Reload your shell
source ~/.zshrc

# Add to ~/.zshrc
zinit load HundredAcreStudio/zsh-claude

# Reload shell
source ~/.zshrc

# Clone the repository
git clone https://github.com/HundredAcreStudio/zsh-claude ~/.zsh-claude

# Add to ~/.zshrc
echo 'source ~/.zsh-claude/zsh-claude.plugin.zsh' >> ~/.zshrc

# Reload shell
source ~/.zshrc

antigen bundle HundredAcreStudio/zsh-claude

zplug "HundredAcreStudio/zsh-claude"

After installation, run the setup command:

claude-setup

This interactive setup will:

1. Prompt for your Claude API key
2. Optional: Configure LiteLLM proxy support
3. Let you choose your preferred AI model
4. Save configuration securely to ~/.config/zsh-claude/config

Available Models:

• Claude 3.5 Haiku (fast, cost-effective) - Recommended
• Claude 3.7 Sonnet (balanced performance)
• Claude Sonnet 4 (high performance, higher cost)
• Claude Sonnet 4.5 (latest model)
• Claude Opus 4.1 (premium, highest cost)

macOS Note: The actual characters produced are « for suggestions and » for explanations

Transform natural language into executable commands:

1. Type your request:

   find all python files modified in the last week
   

2. Press the suggestion key (Option+\ on macOS, Alt+\ on Linux/Windows)

3. Command appears:

   find . -name "*.py" -mtime -7
   

More Examples:

# What you type → What you get
compress all jpg files → tar -czf images.tar.gz *.jpg
delete all node_modules → find . -name "node_modules" -type d -exec rm -rf {} +
show disk usage by directory → du -sh */ | sort -hr

Understand complex commands instantly:

1. Type or paste a command:

   find . -type f -name "*.log" -exec grep -l "ERROR" {} \;
   

2. Press the explanation key (Option+Shift+\ on macOS, Alt+Shift+\ on Linux/Windows)

3. Get detailed breakdown:

   Explanation:
   This command searches for all files with .log extension and finds those containing "ERROR":
   - find . -type f: searches for files starting from current directory
   - -name "*.log": matches files ending with .log
   - -exec grep -l "ERROR" {} \;: runs grep on each file, showing only filenames that contain "ERROR"
   

Use directly from command line:

# Generate suggestions
claude-suggest "compress all jpg files"

# Explain commands
claude-explain "tar -czf archive.tar.gz *.jpg"

# Reconfigure settings
claude-setup

The plugin includes default keybindings, but you can customize them in your ~/.zshrc:

# Default keybindings (automatically set by plugin)
bindkey '»' zsh_claude_explain    # Option+Shift+\ on macOS
bindkey '«' zsh_claude_suggest    # Option+\ on macOS

# Custom alternatives
bindkey "^[s" zsh_claude_suggest   # Alt+s
bindkey "^[e" zsh_claude_explain   # Alt+e
bindkey "^@" zsh_claude_suggest    # Ctrl+space

macOS Users: The actual characters « and » are produced by Option+\ and Option+Shift+\ respectively

• zsh_claude_suggest: Generate command suggestions
• zsh_claude_explain: Explain current command

Advanced users can edit ~/.config/zsh-claude/config:

ZSH_CLAUDE_API_KEY="your-api-key"
ZSH_CLAUDE_MODEL="claude-3-5-haiku-20241022"
ZSH_CLAUDE_API_URL="https://api.anthropic.com/v1/messages"
ZSH_CLAUDE_MAX_TOKENS="1000"
ZSH_CLAUDE_USE_LITELLM="false"

zsh-claude supports LiteLLM proxy for using alternative LLM providers or custom endpoints:

# Run claude-setup and select LiteLLM proxy option
claude-setup

# Or manually configure in ~/.config/zsh-claude/config:
ZSH_CLAUDE_USE_LITELLM="true"
ZSH_CLAUDE_API_URL="http://localhost:4000/v1/messages"
ZSH_CLAUDE_API_KEY="your-litellm-key"

When LiteLLM mode is enabled, the plugin automatically uses OpenAI-compatible authentication (Authorization: Bearer) instead of Anthropic's native format.

# Show loading messages even with Powerlevel10k instant prompt
export ZSH_CLAUDE_VERBOSE=1

# Add to ~/.zshrc before loading the plugin

# Add to ~/.zshrc before loading the plugin
export ZSH_CLAUDE_VERBOSE=1

typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet

# macOS
brew install curl jq

# Ubuntu/Debian
sudo apt install curl jq

# CentOS/RHEL
sudo yum install curl jq

claude-setup

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.

This plugin is inspired by:

• zsh-github-copilot by loiccoyle
• GitHub Copilot CLI

• ✨ Standalone Claude AI integration
• 🚀 Command suggestion functionality
• 📖 Command explanation functionality
• 📦 Support for multiple plugin managers
• ⌨️ Cross-platform keybindings
• 🔒 Secure API key management
• 🎯 Multiple AI model support