zsh-claude

October 2, 2025 · View on GitHub

🤖 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

Claude API Key: Get one from console.anthropic.com/settings/keys
curl: For API requests (usually pre-installed)

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

Click to expand

Antigen:

antigen bundle HundredAcreStudio/zsh-claude

Zplug:

zplug "HundredAcreStudio/zsh-claude"

⚙️ Configuration

After installation, run the setup command:

claude-setup

This interactive setup will:

Prompt for your Claude API key
Optional: Configure LiteLLM proxy support
Let you choose your preferred AI model
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:

Type your request:

find all python files modified in the last week

Press the suggestion key (Option+\ on macOS, Alt+\ on Linux/Windows)
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:

Type or paste a command:

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

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

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

Powerlevel10k instant prompt warning

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

Missing dependencies

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

API key issues

Problem: "No API key found" error

Solution: Run setup:

claude-setup

Problem: "API Error: invalid api key"

Solution:

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

Usage Issues

Keybindings not working

Problem: Keys don't trigger suggestions

Solutions:

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

No suggestions/explanations

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"

Performance issues

Problem: Slow responses