zsh-ai

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

Features

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

Smart Keybinding

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 |

Installation

Requirements

• Node.js 18+
• Codex CLI (npm install -g @openai/codex)
• fzf (for autocomplete)

Install

npm install -g zsh-ai
zsh-ai init
exec zsh

Verify Installation

zsh-ai doctor

Usage

Keybindings

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

# Type a command, press Ctrl+E to explain it:
find . -type f -size +100M
→ "Find all regular files larger than 100MB in the current directory"

# After a command fails, press Ctrl+E on empty line to fix:
$ git pish  # typo, exits with error
$ <Ctrl+E>
→ git push

Alt+A - AI Autocomplete

# Type partial command, press Alt+A for suggestions:
git sta<Alt+A>
→ fzf menu with: git status, git stash, git stash list, etc.

CLI Commands

# 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" 1

# Management
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:

# 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: no

# Add custom redaction patterns (comma-separated regexes)
zstyle ':zsh-ai:redact' extra-patterns 'my-secret-pattern,company-internal-.*'

Environment Variables

# 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

Automatic Redaction

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

Custom Redaction Patterns

Add your own patterns via zstyle:

# Single pattern
zstyle ':zsh-ai:redact' extra-patterns 'my-secret-.*'

# Multiple patterns (comma-separated)
zstyle ':zsh-ai:redact' extra-patterns 'pattern1,pattern2,pattern3'

Opt-in History

By default, command history is never sent to the AI. You can enable it for better fix suggestions:

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

Timeouts

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.

export ZSH_AI_TIMEOUT="10000"  # 10 seconds

Disable

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

# Clone and install
git clone https://github.com/Bigsy/zsh-ai
cd zsh-ai
npm install

# Build
npm run build

# Watch mode
npm run dev

# Link for local testing
npm link

Troubleshooting

Daemon not starting

zsh-ai doctor  # Check all dependencies
zsh-ai stop    # Stop any stuck daemon
zsh-ai start   # Start fresh

Alt+A not working

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+A

Or remap to a different key:

zstyle ':zsh-ai:keybind' complete '^X^A'  # Ctrl+X Ctrl+A instead

Requests timing out

Increase the timeout:

export ZSH_AI_TIMEOUT="30000"  # 30 seconds

Or restart the daemon:

zsh-ai stop
zsh-ai start
zsh-ai status  # Should show "ready"

License

MIT

Credits

• Architecture inspired by codex-cli-command
• Feature design inspired by fish-ai
• Powered by Codex CLI