Get AI-powered command suggestions directly in your zsh shell. No complex setup, no external tools - just press CTRL + O and get intelligent command suggestions powered by OpenAI, Azure OpenAI, Anthropic Claude, or Google Gemini.

• 🚀 Context-aware intelligent prediction: Predicts the next command you are likely to input based on context (history, aliases, terminal buffer)
• 🤖 Multiple AI Providers: Support for OpenAI GPT, Azure OpenAI, Anthropic Claude, and Google Gemini
• 🔧 Highly Configurable: Customize keybindings, AI provider, context sharing, and more

• Why don't I use zsh-copilot and instead fork a separate version?

  Because the context of zsh-copilot only includes history commands and does not include the terminal buffer (i.e., the stdout/stderr of history commands), it cannot achieve the context-aware intelligent prediction I want, this is the feature I want the most, and it's also the main reason why I forked. Additionally, since zsh-copilot is written in shell, it's very difficult to concatenate JSON and implement stdio interception. Therefore, I re-implemented almost all logic using Go, which made it too different from the original project to merge back.

Make sure you have the following installed:

• zsh shell
• zsh-autosuggestions plugin
• An API key for one of the supported AI providers

The easiest way to install smart-suggestion is using our installation script:

curl -fsSL https://raw.githubusercontent.com/XYenon/smart-suggestion/main/install.sh | bash

This script will:

• Detect your platform (Linux, macOS, Android)
• Download the appropriate pre-built binary
• Install the plugin to its installation directory (e.g., ~/.config/smart-suggestion or ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/smart-suggestion if Oh My Zsh is detected)
• Add the plugin to your ~/.zshrc automatically (with Oh My Zsh, you will be instructed to run omz plugin enable smart-suggestion instead)
• Check for zsh-autosuggestions dependency

Uninstall:

curl -fsSL https://raw.githubusercontent.com/XYenon/smart-suggestion/main/install.sh | bash -s -- --uninstall

1. Clone the repository into your Oh My Zsh custom plugins directory:

git clone https://github.com/XYenon/smart-suggestion ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/smart-suggestion

2. Add smart-suggestion to your plugins array in ~/.zshrc:

omz plugin enable smart-suggestion

3. Build the Go binary:

cd ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/smart-suggestion
./build.sh

4. Reload your shell:

source ~/.zshrc

1. Add the following to your ~/.zshrc:

zinit as"program" atclone'./build.sh' \
    atpull'%atclone' pick"smart-suggestion" src"smart-suggestion.plugin.zsh" for \
        XYenon/smart-suggestion

2. Update Zinit:

zi update

1. Clone the repository:

git clone https://github.com/XYenon/smart-suggestion ~/.config/smart-suggestion

2. Build the Go binary (requires Go 1.26+):

cd ~/.config/smart-suggestion
./build.sh

3. Add to your ~/.zshrc:

source ~/.config/smart-suggestion/smart-suggestion.plugin.zsh

4. Reload your shell:

source ~/.zshrc

1. Download the latest release for your platform from GitHub Releases

2. Extract the archive:

mkdir -p ~/.config/smart-suggestion
tar -xzf smart-suggestion-*.tar.gz -C ~/.config/smart-suggestion --strip-components=1

3. Add to your ~/.zshrc:

source ~/.config/smart-suggestion/smart-suggestion.plugin.zsh

4. Reload your shell:

source ~/.zshrc

The recommended way to configure smart-suggestion is by creating a config.zsh file in your configuration directory (default: ~/.config/smart-suggestion/config.zsh).

# ~/.config/smart-suggestion/config.zsh
OPENAI_API_KEY="your-openai-api-key"
OPENAI_API_TYPE="responses" # Optional, "chat_completions" (default) or "responses"
OPENAI_REASONING_EFFORT="medium" # Optional, "none", "minimal", "low", "medium", "high", "xhigh", or "max" (for reasoning models, varies by model)

# ~/.config/smart-suggestion/config.zsh
AZURE_OPENAI_API_KEY="your-azure-openai-api-key" # i.e. c0123456789012345678901234567890
AZURE_OPENAI_RESOURCE_NAME="your-azure-openai-resource-name" # i.e. awesome-corp when your endpoint is https://awesome-corp.openai.azure.com
AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment-name" # i.e. gpt-5.6-terra
AZURE_OPENAI_API_VERSION="2025-04-01-preview"  # Optional, defaults to 2025-04-01-preview
AZURE_OPENAI_BASE_URL="https://your-azure-openai-base-url" # Optional, default to https://$AZURE_OPENAI_RESOURCE_NAME.openai.azure.com
AZURE_OPENAI_REASONING_EFFORT="medium" # Optional, "none", "minimal", "low", "medium", "high", "xhigh", or "max" (varies by model)

# ~/.config/smart-suggestion/config.zsh
ANTHROPIC_API_KEY="your-anthropic-api-key"
ANTHROPIC_REASONING_EFFORT="medium" # Optional, "low", "medium", "high", "xhigh", or "max" (varies by model)

# ~/.config/smart-suggestion/config.zsh
GEMINI_API_KEY="your-gemini-api-key"
GEMINI_THINKING_LEVEL="high" # Optional, "minimal", "low", "medium", or "high" (varies by model)

Set a TypeSafe API key to enable a fast path that selects only commands already present in shell history. Jev ranks a locally built shortlist and never generates command text. Errors, timeouts, uncertain results, and none selections automatically fall back to the configured LLM provider.

# ~/.config/smart-suggestion/config.zsh
TYPESAFE_API_KEY="your-typesafe-api-key"

Alternatively, you can configure the plugin using global environment variables in your .zshrc (requires export).

If SMART_SUGGESTION_BINARY is not specified, we look for one in the following locations:

1. smart-suggestion beside the current smart-suggestion.plugin.zsh
2. smart-suggestion beside your config.zsh (the directory of $SMART_SUGGESTION_CONFIG, default ~/.config/smart-suggestion)

# ~/.config/smart-suggestion/config.zsh
OPENAI_BASE_URL="your-custom-openai-endpoint.com"
AZURE_OPENAI_BASE_URL="your-custom-azure-openai-endpoint.com"
ANTHROPIC_BASE_URL="your-custom-anthropic-endpoint.com"
GEMINI_BASE_URL="your-custom-gemini-endpoint.com"

# ~/.config/smart-suggestion/config.zsh
OPENAI_MODEL="gpt-5.5"          # Default: gpt-5.6-terra
ANTHROPIC_MODEL="claude-opus-5" # Default: claude-sonnet-5
GEMINI_MODEL="gemini-3.1-pro-preview"  # Default: gemini-3.7-flash

# ~/.config/smart-suggestion/config.zsh
# OpenAI
OPENAI_REASONING_EFFORT="medium"        # Options: none, minimal, low, medium, high, xhigh, max

# Azure OpenAI
AZURE_OPENAI_REASONING_EFFORT="medium"  # Options: none, minimal, low, medium, high, xhigh, max

# Anthropic Claude
ANTHROPIC_REASONING_EFFORT="medium"     # Options: low, medium, high, xhigh, max

# Google Gemini
GEMINI_THINKING_LEVEL="high"            # Options: minimal, low, medium, high

# ~/.config/smart-suggestion/config.zsh
SMART_SUGGESTION_HISTORY_LINES="20"  # Default: 10

# ~/.config/smart-suggestion/config.zsh
OPENAI_API_TYPE="responses"          # Default: chat_completions, options: chat_completions, responses

To see all available configurations and their current values:

smart-suggestion

1. Start typing a command or describe what you want to do
2. Press CTRL + O (or your configured key)
3. Wait for the AI suggestion (loading animation will show)
   • Note: Unless your terminal provides native scrollback (see below), proxy mode automatically wraps your shell session in a recorder at shell startup to capture terminal context
4. The suggestion will appear as:
   • An autosuggestion you can accept with → (for completions)
   • A completely new command that replaces your input (for new commands)

Besides the suggestion flow invoked by the plugin, the smart-suggestion binary ships a few subcommands:

• smart-suggestion update: Update the binary and plugin to the latest GitHub release. The plugin notifies you when an update is available; run this to install it.
• smart-suggestion update --check-only: Only check whether a newer release is available, without installing.
• smart-suggestion rotate-logs --log-file <path>: Rotate a log file (safe to run while the proxy is still writing it).
• smart-suggestion version: Print version, build time, git commit, OS, and architecture.

1. Input Capture: The plugin captures your current command line input
2. Proxy Mode (Default): Wraps your shell session in a PTY-based recorder at shell startup to capture terminal output for better context (skipped when a terminal with native scrollback integration is detected)
3. Context Collection: Gathers rich shell context including user info, directory, command history, aliases, and terminal scrollback content via proxy mode
4. AI Processing: Sends the input and context to your configured AI provider
5. Smart Response: AI returns either a completion (+) or new command (=)
6. Shell Integration: The suggestion is displayed using zsh-autosuggestions or replaces your input

Smart Suggestion automatically enables proxy mode by default, which provides significantly better context awareness by recording your terminal session. This mode:

• Starts automatically when your shell starts, wrapping your session in a PTY-based recorder (no external tools required)
• Records terminal output through a PTY while preserving the original terminal stream
• Renders terminal state with charmbracelet/x/vt, so cursor movement, screen clearing, alternate screens, and wide characters are captured accurately
• Provides rich context to the AI including command outputs and error messages
• Works seamlessly across different terminal environments
• Is skipped when a terminal with native scrollback integration is detected (Tmux, Herdr, Kitty, Ghostty; see below)

You can disable proxy mode if needed:

# ~/.config/smart-suggestion/config.zsh
SMART_SUGGESTION_PROXY_MODE=false

Smart Suggestion automatically detects and uses native scrollback APIs for supported terminals, without requiring proxy mode:

To enable native scrollback support in Ghostty, add the following to your Ghostty config (~/.config/ghostty/config):

keybind = unconsumed:ctrl+o=write_screen_file:paste

Enable debug logging to troubleshoot issues:

# ~/.config/smart-suggestion/config.zsh
SMART_SUGGESTION_DEBUG=true

Debug logs are written to ~/.cache/smart-suggestion/debug.log.

1. "Binary not found" error: Run ./build.sh in the plugin directory
2. No suggestions: Check your API key and internet connection
3. Wrong suggestions: Try adjusting the context settings or system prompt
4. Key binding conflicts: Change SMART_SUGGESTION_KEY to a different key

If the build fails:

# Check Go installation
go version

# Clean and rebuild
rm -f smart-suggestion
./build.sh

Contributions are welcome! Please feel free to submit issues and pull requests.