AI-powered shell assistance for zsh
npm install zsh-aiAI-powered shell assistance for zsh. Convert comments to commands, explain commands, get intelligent autocomplete suggestions, and fix failed commands - all with simple keybindings.
Inspired by fish-ai, built for zsh/oh-my-zsh users.
| Feature | Keybinding | Description |
|---------|------------|-------------|
| Codify | Ctrl+E | Convert # comment to a shell command |
| Explain | Ctrl+E | Explain what a command does |
| Fix | Ctrl+E | Fix the last failed command |
| Autocomplete | Alt+A | Get AI-powered completions via fzf |
Ctrl+E is context-aware and automatically picks the right action:
| Buffer State | Action |
|--------------|--------|
| Empty + failed command exists | Fix the failed command |
| # find large files | Codify → convert to find . -size +100M |
| find . -size +100M | Explain → show what it does |
- Node.js 18+
- Codex CLI (npm install -g @openai/codex)
- fzf (for autocomplete)
``bash`
npm install -g zsh-ai
zsh-ai init
exec zsh
`bash`
zsh-ai doctor
Ctrl+E - Smart AI (context-aware)
`Type a comment, press Ctrl+E to convert to command:
list all files larger than 100mb
→ find . -type f -size +100M
Alt+A - AI Autocomplete
`
Type partial command, press Alt+A for suggestions:
git sta
→ fzf menu with: git status, git stash, git stash list, etc.
`$3
`bash
AI commands
zsh-ai codify "# find python files modified today"
zsh-ai explain "tar -xzvf archive.tar.gz"
zsh-ai complete "docker "
zsh-ai fix "git pish" 1Management
zsh-ai start # Start the background daemon
zsh-ai stop # Stop the daemon
zsh-ai status # Check daemon status
zsh-ai doctor # Verify dependencies
`Configuration
Configure via zstyle in your
.zshrc:`zsh
Disable the plugin
zstyle ':zsh-ai:*' enabled 'no'Custom keybindings
zstyle ':zsh-ai:keybind' smart '^E' # Default: Ctrl+E
zstyle ':zsh-ai:keybind' complete '^a' # Default: Alt+A (ESC-a)Enable history context for fix (opt-in, privacy-sensitive)
zstyle ':zsh-ai:context' history 'yes' # Default: noAdd custom redaction patterns (comma-separated regexes)
zstyle ':zsh-ai:redact' extra-patterns 'my-secret-pattern,company-internal-.*'
`$3
`bash
Override the AI model
export ZSH_AI_MODEL="gpt-4o"Custom timeout in milliseconds (default: 15000)
export ZSH_AI_TIMEOUT="30000"
`Architecture
`
┌─────────────────────────────────────────────────────┐
│ zsh-ai plugin │
│ (ZLE widgets, keybindings) │
│ │
│ Ctrl+E: smart (fix/codify/explain) │
│ Alt+A: autocomplete │
└───────────────────────┬─────────────────────────────┘
│ Unix Socket
┌───────────────────────▼─────────────────────────────┐
│ Daemon │
│ - Keeps Codex MCP server warm │
│ - Handles JSON-RPC requests │
│ - /tmp/zsh-ai.sock │
│ - Configurable timeout (default 15s) │
└───────────────────────┬─────────────────────────────┘
│
▼
┌─────────────┐
│ codex mcp │
│ server │
└─────────────┘
`The daemon architecture ensures instant responses by keeping the AI backend warm. All requests go through a Unix socket with configurable timeouts to never block your shell.
Privacy & Security
$3
Before sending any input to the AI (commands, comments, and history if enabled), sensitive data is automatically redacted:
- API keys and tokens (
api_key=..., OPENAI_API_KEY=...)
- AWS credentials (AKIA..., aws_secret_access_key)
- Private keys (-----BEGIN PRIVATE KEY-----)
- Bearer tokens
- Database URLs with credentials
- JWT tokens
- GitHub tokens (ghp_..., ghs_...)> Note: These patterns are not foolproof. Be mindful of what you type - unusual secret formats or company-specific patterns may not be caught. Add custom patterns for your environment (see below).
$3
Add your own patterns via zstyle:
`zsh
Single pattern
zstyle ':zsh-ai:redact' extra-patterns 'my-secret-.*'Multiple patterns (comma-separated)
zstyle ':zsh-ai:redact' extra-patterns 'pattern1,pattern2,pattern3'
`$3
By default, command history is never sent to the AI. You can enable it for better fix suggestions:
`zsh
zstyle ':zsh-ai:context' history 'yes'
`When enabled, the last 3 commands are sent with fix requests to provide context. These commands are redacted using the same patterns as all other input (API keys, tokens, etc. are stripped before sending).
$3
All requests have a configurable timeout (default 15s). The shell is never blocked - if the AI doesn't respond, you get an error message and can continue working.
`bash
export ZSH_AI_TIMEOUT="10000" # 10 seconds
`$3
`zsh
zstyle ':zsh-ai:*' enabled 'no'
`File Structure
`
zsh-ai/
├── bin/
│ └── zsh-ai # CLI entry point
├── dist/ # Compiled TypeScript
├── src/
│ ├── index.ts # CLI implementation
│ ├── daemon.ts # Background daemon
│ ├── client.ts # Socket client
│ ├── mcp.ts # MCP JSON-RPC helpers
│ └── redact.ts # Privacy redaction
├── plugin/
│ ├── zsh-ai.plugin.zsh # Main plugin file
│ └── lib/
│ ├── widgets.zsh # ZLE widgets
│ └── hooks.zsh # preexec/precmd hooks
├── package.json
└── tsconfig.json
`Development
`bash
Clone and install
git clone https://github.com/Bigsy/zsh-ai
cd zsh-ai
npm installBuild
npm run buildWatch mode
npm run devLink for local testing
npm link
`Troubleshooting
$3
`bash
zsh-ai doctor # Check all dependencies
zsh-ai stop # Stop any stuck daemon
zsh-ai start # Start fresh
`$3
Some terminals intercept Alt keys. Try:
- iTerm2: Preferences → Profiles → Keys → Left Option Key → Esc+
- Terminal.app: May need to use
Esc then a instead of Alt+AOr remap to a different key:
`zsh
zstyle ':zsh-ai:keybind' complete '^X^A' # Ctrl+X Ctrl+A instead
`$3
Increase the timeout:
`bash
export ZSH_AI_TIMEOUT="30000" # 30 seconds
`Or restart the daemon:
`bash
zsh-ai stop
zsh-ai start
zsh-ai status # Should show "ready"
``MIT
- Architecture inspired by [codex-cli-command
- Feature design inspired by fish-ai
- Powered by Codex CLI