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 |

$3

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

$3

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

$3

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

`$3`

`bash zsh-ai doctor`

`Usage`

`$3`

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
$ 
→ git push

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

`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: no
Add 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 install
Build

npm run build
Watch mode

npm run dev
Link 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`

zsh-ai

zsh-ai

Features

$3

Installation

$3

$3

$3

Usage

$3

Type a comment, press Ctrl+E to convert to command:

list all files larger than 100mb

Type a command, press Ctrl+E to explain it:

After a command fails, press Ctrl+E on empty line to fix:

Type partial command, press Alt+A for suggestions:

$3

AI commands

Management

Configuration

Disable the plugin

Custom keybindings

Enable history context for fix (opt-in, privacy-sensitive)

Add custom redaction patterns (comma-separated regexes)

$3

Override the AI model

Custom timeout in milliseconds (default: 15000)

Architecture

Privacy & Security

$3

$3

Single pattern

Multiple patterns (comma-separated)

$3

$3

$3

File Structure

Development

Clone and install

Build

Watch mode

Link for local testing

Troubleshooting

$3

$3

$3

License

Credits

zsh-ai

zsh-ai

Features

$3

Installation

$3

$3

$3

Usage

$3

Type a comment, press Ctrl+E to convert to command:

list all files larger than 100mb

Type a command, press Ctrl+E to explain it:

After a command fails, press Ctrl+E on empty line to fix:

Type partial command, press Alt+A for suggestions:

$3

AI commands

Management

Configuration

Disable the plugin

Custom keybindings

Enable history context for fix (opt-in, privacy-sensitive)

Add custom redaction patterns (comma-separated regexes)

$3

Override the AI model

Custom timeout in milliseconds (default: 15000)

Architecture

Privacy & Security

$3

$3

Single pattern

Multiple patterns (comma-separated)

$3

`$3`

`Usage`

`$3`

`Type a comment, press Ctrl+E to convert to command:`

`Type partial command, press Alt+A for suggestions:`

`AI commands`

`Disable the plugin`

`Override the AI model`

`Privacy & Security`

`$3`

`$3`

`Single pattern`

`$3`

`$3`

`File Structure`

`Development`

`Clone and install`

`$3`

`$3`

`$3`

`Usage`

`$3`

`Type a comment, press Ctrl+E to convert to command:`

`Type partial command, press Alt+A for suggestions:`

`AI commands`

`Disable the plugin`

`Override the AI model`

`Privacy & Security`

`$3`

`$3`

`Single pattern`

`$3`

`$3`

`File Structure`

`Development`

`Clone and install`

`$3`

`$3`