zsh-claude

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

✨ Features

• 🧠 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

🚀 Quick Start

Prerequisites

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
   

📦 Installation

Method 1: Oh My Zsh (Recommended)

# 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

Method 2: Zinit

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

# Reload shell
source ~/.zshrc

Method 3: Manual Installation

# 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

Other Plugin Managers

<details> <summary>Click to expand</summary>

Antigen:

antigen bundle HundredAcreStudio/zsh-claude

Zplug:

zplug "HundredAcreStudio/zsh-claude"

</details>

⚙️ Configuration

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)

🎯 Usage

Keybindings

| Platform | Suggest Command | Explain Command | |----------|----------------|-----------------| | macOS | Option + \ («) | Option + Shift + \ (») | | Linux/Windows | Alt + \ | Alt + Shift + \ |

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

💡 Command Suggestions

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

📚 Command Explanations

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"
   

🔧 Manual Commands

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

🎨 Customization

Custom Keybindings

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

Available Widgets

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

Configuration File

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"

LiteLLM Proxy Support

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.

Environment Variables

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

# Add to ~/.zshrc before loading the plugin

🔧 Troubleshooting

Installation Issues

<details> <summary>Powerlevel10k instant prompt warning</summary>

Problem: Warning about console output during zsh initialization

Solution: This is normal behavior. The plugin automatically suppresses loading messages when Powerlevel10k instant prompt is detected.

To see loading messages anyway:

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

Or suppress the warning by adding to ~/.zshrc:

typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet

</details> <details> <summary>Missing dependencies</summary>

Problem: "Missing required dependencies" error

Solution: Install missing tools:

# macOS
brew install curl jq

# Ubuntu/Debian
sudo apt install curl jq

# CentOS/RHEL
sudo yum install curl jq

</details> <details> <summary>API key issues</summary>

Problem: "No API key found" error

Solution: Run setup:

claude-setup

Problem: "API Error: invalid api key"

Solution:

1. Get a valid API key from console.anthropic.com/settings/keys
2. Run claude-setup to update your key

</details>

Usage Issues

<details> <summary>Keybindings not working</summary>

Problem: Keys don't trigger suggestions

Solutions:

1. Check terminal compatibility
2. Try custom keybindings (see Customization section)
3. Test with manual commands: claude-suggest "test"

</details> <details> <summary>No suggestions/explanations</summary>

Problem: Commands return no results

Checklist:

• ✅ Internet connection working
• ✅ API key is valid (claude-setup)
• ✅ API credits available
• ✅ Model name is correct
• ✅ Test with: claude-suggest "list files"

</details> <details> <summary>Performance issues</summary>

Problem: Slow responses

Solutions:

1. Switch to faster model (Claude 3.5 Haiku)
2. Check internet connection
3. Reduce ZSH_CLAUDE_MAX_TOKENS in config

</details>

🤝 Contributing

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

📄 License

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

🙏 Inspiration

This plugin is inspired by:

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

📋 Changelog

v1.0.0

• ✨ 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