zsh-claude-code

Claude-powered helpers for your zsh prompt. Ask questions, explain commands, and turn natural language into shell commands - without leaving the terminal.

All four features wrap the claude CLI (Claude Code) in --print mode, so if you're already logged in with claude login there's nothing else to set up.

• Ctrl+X - describe a command in plain English, press to rewrite the line into shell.
• Alt+E - type or paste a command, press to print an explanation above it.

Features

Requirements

• zsh 5.0+
• claude CLI installed and authenticated (either claude login or ANTHROPIC_API_KEY in the environment)
• No other runtime dependencies

Installation

zinit (recommended)

Requires zinit. Add to your ~/.zshrc after zinit is initialized:

zinit light matheus-poli/zsh-claude-code

Restart your shell or source ~/.zshrc.

oh-my-zsh

If you use oh-my-zsh, clone into the custom plugins dir:

git clone https://github.com/matheus-poli/zsh-claude-code \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-claude-code"

Add zsh-claude-code to your plugins=(...) in ~/.zshrc, then restart your shell or source ~/.zshrc.

Manual

git clone https://github.com/matheus-poli/zsh-claude-code ~/.zsh-claude-code
echo 'source ~/.zsh-claude-code/zsh-claude-code.plugin.zsh' >> ~/.zshrc

Usage

ask

ask how do I list files modified in the last 24 hours
ask "what's the difference between \$* and \$@ in zsh?"

Prints a terse answer. If the answer is a command, it shows the command first in a fenced block, then at most one short line of context.

explain

explain 'find . -type f -exec md5sum {} + | sort | uniq -w32 -dD'

Prints one overview line + a short bullet per flag/argument.

Wrap the command in single quotes whenever it contains shell metacharacters (|, >, <, &, ;, $, backticks). noglob only suppresses glob expansion (*, ?, [...]); it doesn't stop zsh from parsing pipes or redirects, so an unquoted pipeline would actually run.

Suggest widget (Ctrl+X)

Type a natural-language request, then press Ctrl+X:

find all js files larger than 100kb modified in the last week

becomes:

find . -name "*.js" -size +100k -mtime -7

Review the command, press Enter to run (or edit first).

Explain widget (Alt+E)

Type or paste a command at the prompt, then press Alt+E. The explanation prints above the prompt; your command stays intact so you can still edit or run it.

Configuration

Set any of these in ~/.zshrc before the plugin loads (especially keybinds - they're resolved at source time).

Example: change keybind and use a stronger ask model

# ~/.zshrc - BEFORE the plugins=(...) line
export ZSH_CLAUDE_SUGGEST_KEY='^G'     # Ctrl+G instead of Ctrl+X
export ZSH_CLAUDE_ASK_MODEL='opus'     # stronger model for ask, slower

Troubleshooting

• "command not found: claude" - the plugin no-ops gracefully when claude isn't on $PATH. Install Claude Code and run claude login.
• Widget doesn't fire - another plugin may have rebound ^X. Try setting ZSH_CLAUDE_SUGGEST_KEY to something else, or use bindkey | grep claude to confirm the binding.
• Output has stray backticks / code fences - please open an issue with the input that produced it. The suggest widget already scrubs fences defensively, but prompts evolve.

Contributing

Contributions welcome - PRs, bug reports, feature ideas. Quick start:

git clone https://github.com/matheus-poli/zsh-claude-code
cd zsh-claude-code
mise run setup     # pinned tools, commitlint deps, git hooks — one command
mise run check     # lint + unit tests + smoke

If anything feels off, mise run doctor walks through the environment and tells you exactly what's missing.

First time using mise? Install it once globally (it pins per-project versions of node, bats, lefthook), then the commands above work from any fresh clone.

Available tasks:

Commits follow Conventional Commits (feat:, fix:, docs:, chore:, …) - enforced by commitlint via a lefthook commit-msg hook. This drives automated semver releases.

Manual test checklist before sending a PR that touches the plugin code:

• ask and explain with ?, !, *, and quoted strings
• Ctrl+X with a clear request and an ambiguous one
• Alt+E on a typed command - original command must stay intact
• All four features with claude logged out → helpful error, not a crash
• Custom keybinds set before plugin load

See CLAUDE.md for design notes and the full rationale behind each decision.

Contributors

Matheus Poli 💻 📖 🚧 🎨 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

To add yourself after a merged PR, comment on the PR:

@all-contributors please add @your-username for code, doc

License

MIT © Matheus Poli