Oh My Zsh AI CLI Plugins

March 4, 2026 · View on GitHub

A collection of intelligent Zsh completion plugins for popular AI CLI tools, providing comprehensive auto-completion support for Claude Code, Codex, and Gemini CLI.

Features

Smart Auto-completion: Intelligent command and option completion for all supported AI CLI tools
Comprehensive Coverage: Complete support for all commands, subcommands, and parameters
Dynamic Context: Context-aware completions based on available configurations
Convenient Aliases: Pre-configured short aliases for frequently used commands
Easy Installation: Automated installation script with environment detection
Clean Uninstallation: Simple removal with backup preservation

Supported Tools

Claude (`claude`)

Complete auto-completion for Claude Code, Anthropic's official CLI tool for Claude.

Supported Commands:

agents - List configured agents
auth - Manage authentication
install - Install Claude Code native version
mcp - Configure and manage MCP servers
plugin - Manage Claude Code plugins
setup-token - Configure long-term authentication token
doctor - Check auto-updater health
update|upgrade - Check and install updates

Aliases:

cc → claude
ccc → claude chat
cca → claude api
cccfg → claude config

Codex (`codex`)

Full auto-completion support for Codex, an AI-powered coding assistant.

Supported Commands:

app - Launch Codex desktop app
exec - Run Codex non-interactively
review - Run code review non-interactively
mcp - Manage MCP servers
login/logout - Manage authentication
app-server - Run app server tooling
debug - Run debugging tools
sandbox - Run commands in Codex-provided sandbox
apply - Apply latest diff to local working tree
resume - Resume previous interactive session
fork - Fork previous interactive session
cloud - Browse Codex Cloud tasks
features - Inspect and update feature flags

Aliases:

cdx → codex
cdxa → codex ask
cdxc → codex chat
cdxe → codex explain
cdxf → codex fix
cdxr → codex review
cdxt → codex test
cdxrf → codex refactor
cdxcfg → codex config

Gemini (`gemini`)

Intelligent completion for Gemini CLI, Google's Gemini command-line interface.

Supported Commands:

mcp - Manage MCP servers
extensions - Manage Gemini CLI extensions
skills - Manage agent skills
hooks - Manage Gemini CLI hooks

Aliases:

gm → gemini
gmm → gemini mcp
gme → gemini extensions

Requirements

Oh My Zsh - Zsh configuration framework
Zsh 5.0 or higher
At least one of the following AI CLI tools installed:

Installation

Quick Install

# Clone the repository
git clone https://github.com/YOUR_USERNAME/ohmyzsh-plugins.git
cd ohmyzsh-plugins

# Run the installation script
bash install.sh

The installation script will:

Detect your environment and installed AI CLI tools
Copy plugin files to ~/.oh-my-zsh/custom/plugins/
Automatically update your .zshrc configuration
Create a backup of your .zshrc file

Reload Your Shell

After installation, reload your shell configuration:

# Option 1: Reload shell (recommended)
exec zsh

# Option 2: Source configuration
source ~/.zshrc

Usage

Auto-completion Examples

Simply type the command and press Tab to see available completions:

# Claude Code
claude [Tab]              # Shows main commands
claude mcp [Tab]          # Shows MCP subcommands
claude plugin [Tab]       # Shows plugin management commands

# Codex
codex [Tab]               # Shows main commands
codex mcp [Tab]           # Shows MCP operations
codex exec [Tab]          # Shows execution options

# Gemini CLI
gemini [Tab]              # Shows main commands
gemini mcp [Tab]          # Shows MCP management
gemini extensions [Tab]   # Shows extension operations

Using Aliases

# Claude Code shortcuts
cc                        # Instead of 'claude'
ccc "your prompt"         # Quick chat
cccfg                     # Quick config

# Codex shortcuts
cdx                       # Instead of 'codex'
cdxa "explain this code"  # Quick ask
cdxr                      # Quick review

# Gemini CLI shortcuts
gm                        # Instead of 'gemini'
gmm list                  # Quick MCP list
gme list                  # Quick extension list

Advanced Features

Context-Aware Completions

The plugins provide intelligent, context-aware completions:

MCP Server Names: Dynamically lists configured MCP servers
Extension Names: Shows installed extensions for management commands
File Paths: Provides file completion where appropriate
Option Values: Suggests valid values for enumerated options

Multi-line Plugin Configuration

The installation script supports both single-line and multi-line plugins arrays in .zshrc:

# Single-line format
plugins=(git brew claude codex gemini)

# Multi-line format
plugins=(
  git
  brew
  claude
  codex
  gemini
)

Configuration Scopes

Many commands support configuration scopes:

user - User-level configuration
project - Project-specific configuration
local - Local machine configuration

Example:

claude mcp add --scope user myserver
gemini mcp add --scope project toolserver

Uninstallation

To remove the plugins:

bash uninstall.sh

The uninstall script will:

Remove plugin files from ~/.oh-my-zsh/custom/plugins/
Remove plugin entries from your .zshrc
Create a backup before making changes
Clean up completion cache

Troubleshooting

Completions Not Working

If auto-completions don't work after installation:

# Clear completion cache
rm -f ~/.zcompdump*

# Reload shell
exec zsh

Plugin Not Loading

Check if the plugin is properly added to your .zshrc:

grep "plugins=" ~/.zshrc

Ensure your desired plugins are listed in the plugins array.

Command Not Found

Verify that the AI CLI tool is installed and in your PATH:

# Check Claude Code
which claude

# Check Codex
which codex

# Check Gemini CLI
which gemini

Sync Check on macOS/Linux

Use the built-in sync checker to verify plugin coverage after upgrading CLI tools:

bash check_sync.sh

Behavior notes:

Uses timeout when available, or gtimeout if installed via Homebrew.
If neither is available, checks still run without timeout protection (may be slower).
Set STRICT_MODE=1 to require timeout support and fail fast in CI:

STRICT_MODE=1 bash check_sync.sh

Interactive E2E Test

Run the full interactive automation test (real zsh + Tab via expect):

bash scripts/test_interactive_completion.sh

What it does:

Auto-discovers command/subcommand/option cases from live claude/codex/gemini --help output
Runs each case in a real interactive zsh session and sends Tab
Fails with non-zero exit code if any expected completion is missing

Optional environment variables:

EXPECT_TIMEOUT=4 to increase per-assert timeout (default: 2)
KEEP_TMP_HOME=1 to keep the temporary isolated HOME for debugging
MAX_DEPTH=2 to limit recursive command depth
CASE_LIMIT=200 to run only first N generated cases for quick iteration
EXPECT_VERBOSE=1 to print PASS lines for every case
STRICT_HELP=0 to allow skipped help output parsing without failing generation

Project Structure

ohmyzsh-plugins/
├── claude/
│   └── claude.plugin.zsh
├── codex/
│   └── codex.plugin.zsh
├── gemini/
│   └── gemini.plugin.zsh
├── scripts/
│   └── test_interactive_completion.sh
├── install.sh
├── uninstall.sh
├── check_sync.sh
├── README.md
├── VERSION
└── LICENSE