Smart Z shell super-powers for fzf.

fzf-ai-tools glues together fzf and aichat to add explain-this-for-me goodness to your Z shell. Pipe your history, aliases, or any file through fuzzy-finder search and ask an LLM for a quick human-readable explanation.

🎥 Demo

✨ Features

• ai:h — History: Fuzzy-search your shell history and have AI explain the chosen command.
• ai:a — Aliases: Browse your defined aliases and let AI decode what that cryptic one-liner does.
• ai:f — Files: Fuzzy-find project files and get a top-of-file interpretation.
• ai:i — Input: Type arbitrary input and ask AI about it (bound to Ctrl-A by default).
• Dependency check that politely yells at you if fzf or aichat are missing.

🚀 Installation

1. Install the runtime dependencies

# Use Homebrew or your package manager of choice

brew install fzf aichat

The aichat tool requires an API key for an LLM. Consult the aichat repository for more information.

2. Grab the plugin

Antidote

antidote bundle stephenhowells/fzf-ai-tools

Oh My Zsh

Clone into ~/.oh-my-zsh/custom/plugins and add fzf-ai-tools to the plugins=(...) array in .zshrc.

git clone https://github.com/stephenhowells/fzf-ai-tools ~/.oh-my-zsh/custom/plugins/fzf-ai-tools

Zinit

zinit light stephenhowells/fzf-ai-tools

Manual (no plugin manager)

Clone the repo anywhere (for example ~/.zsh/fzf-ai-tools) and source the plugin file from your .zshrc:

# Grab the plugin
git clone https://github.com/stephenhowells/fzf-ai-tools ~/.zsh/fzf-ai-tools

# Add to your .zshrc
source ~/.zsh/fzf-ai-tools/fzf-ai-tools.plugin.zsh

3. Reload Zsh

exec zsh

📖 Usage

Alias	Long-form	What it does
ai:h	fzf-ai-history	Fuzzy search your command history. The highlighted line is sent to AI: "Explain this command: …"
ai:a	fzf-ai-aliases	Search your defined aliases and ask: "Explain this alias: …"
ai:f	fzf-ai-files	Fuzzy search files (ignoring dot-files) and request an AI summary of the first 100 lines.
ai:i	fzf-ai-input	Inline prompt: type anything, hit Enter, receive enlightenment.

Keybindings

Key	Action
Ctrl-A	Trigger fzf-ai-input from anywhere in the prompt.

⚙️ Customization

# Change the keybinding to Ctrl-E for the fzf-ai-input command

bindkey '^E' fzf-ai-input

🤔 Troubleshooting

Symptom	Likely Cause	Fix
Blank previews	aichat lacks API key / network.	Configure AICHAT_OPENAI_KEY or whatever AI provider you use.
Slowness	Some LLM responses can take a while.	Try switching to a different AI model in aichat.

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details.